Skip to content

Create Project

POST
/api/v1/projects
curl --request POST \
--url https://sitechecker.pro/api/v1/projects \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "url": "https://example.com", "project_name": "Example", "site_audit": false, "keywords": [ "seo audit", "site checker" ], "geos": [ { "country_code": "US", "language_code": "en", "search_engine": "google", "device": "desktop" } ] }'

Creates one project per request. Creating several projects for the same URL is allowed. With site_audit: false the project is created without Site Audit: it is not crawled and uses none of the plan’s page quota (site_audit_enabled: false in the response). Site Audit can be enabled later in the app by setting a page limit. Pass keywords together with geos to start tracking right away: every keyword is tracked in every geo (keywords × geos, at most 500 pairs), and both count against the plan limits before anything is created. Positions appear after the first rank check; read them with GET /api/v1/keywords?project_id=. If the keywords cannot be saved, the project is removed again, so a failed request never leaves a half-made project.

Media typeapplication/json
object
url
required

Absolute http or https URL of the site. Stored lowercase, without query, fragment and trailing slash.

string
<= 255 characters
project_name

Name shown in Sitechecker. Defaults to the host without “www.”.

string
<= 100 characters
site_audit

False creates the project without Site Audit: no crawl, no page quota used. Must be a JSON boolean.

boolean
default: true
keywords

Keywords to track (at most 100). Requires geos.

Array<string>
geos

Where to track the keywords (at most 10). Requires keywords.

Array<object>

Where and how a keyword is tracked. Codes are case-insensitive. Valid values come from GET /api/v1/rank_tracker_countries, /rank_tracker_languages and /rank_tracker_locations.

object
country_code
required

ISO 3166-1 alpha-2 country code.

string
language_code
required

ISO 639-1 language code.

string
search_engine
string
default: google
Allowed values: google bing yahoo
device

Mobile is available for google only.

string
default: desktop
Allowed values: desktop mobile
location

Optional Google location: a location_name or location_id from GET /api/v1/rank_tracker_locations. Omit or send an empty string to track the whole country. Google only.

string
Example
{
"url": "https://example.com",
"project_name": "Example",
"site_audit": false,
"keywords": [
"seo audit",
"site checker"
],
"geos": [
{
"country_code": "US",
"language_code": "en",
"search_engine": "google",
"device": "desktop"
}
]
}

Project created

Media typeapplication/json
object
data

The created project. Same identity fields as a GET /api/v1/projects row, plus the keywords added with it.

object
project_id

Unique project ID.

integer
project_name

Project name shown in Sitechecker.

string
url

Project domain returned under this key (value = project domain).

string
domain_scope

Domain scope used by the project, returned as an object with protocols, scope_type and path.

object
protocols
Array<string>
scope_type
string
path
string
site_audit_enabled

Whether Site Audit is enabled for the project.

boolean
last_crawl_date

Latest crawl date.

string format: date-time
nullable
last_crawl_status

Latest crawl status. API also returns ‘pending’ (enabled, not yet crawled) or null (audit disabled).

string
nullable
site_audit

Returned only with include=site_audit. Latest crawl metrics of the project, from the same stored audit snapshot as site-audit/audit_summary. Values are null when the project has never been crawled.

object
website_score

Latest website score.

integer
nullable
crawled_pages

Crawled pages count.

integer
nullable
criticals

Critical issues found by the latest crawl.

integer
nullable
warnings

Warnings found by the latest crawl.

integer
nullable
opportunities

Opportunities found by the latest crawl.

integer
nullable
notices

Notices found by the latest crawl.

integer
nullable
ga4_insights

Returned only with include=ga4_insights. GA4 metrics for the project, split by traffic scope — the same figures the Project List columns show. GA4 storage separates organic from total traffic only, so those are the two scopes exposed here. key_events counts the key events configured for the project, while session_key_event_rate is the share of sessions with any key event, following the ga4-insights definition. Both periods are the windows of the stored aggregate; see the endpoint description for how they are refreshed.

object
status

Whether the block holds data: ‘ok’ — data for the period; ‘no_data’ — the source is set up but stored nothing for the period; ‘not_connected’ — the project has no such integration. Every metric is null unless the status is ok, so a null is never confused with a real zero.

string
Allowed values: ok no_data not_connected
period

Date range a metric block was computed for, inclusive. Null when the project has no stored aggregate yet.

object
date_from
string format: date
date_to
string format: date
comparison_period

Date range a metric block was computed for, inclusive. Null when the project has no stored aggregate yet.

object
date_from
string format: date
date_to
string format: date
all_traffic

GA4 metrics for one traffic scope. Each metric is followed by its *_change: the relative change against comparison_period in percent (not percentage points), null when the comparison period had no baseline to compare against.

object
sessions
integer
nullable
sessions_change
number format: float
nullable
bounce_rate

Session-weighted bounce rate, percent (0-100).

number format: float
nullable
bounce_rate_change
number format: float
nullable
average_session_duration

Session-weighted average session duration, in seconds.

number format: float
nullable
average_session_duration_change
number format: float
nullable
key_events
integer
nullable
key_events_change
number format: float
nullable
session_key_event_rate

Share of sessions with a key event, percent (0-100).

number format: float
nullable
session_key_event_rate_change
number format: float
nullable
organic_search

GA4 metrics for one traffic scope. Each metric is followed by its *_change: the relative change against comparison_period in percent (not percentage points), null when the comparison period had no baseline to compare against.

object
sessions
integer
nullable
sessions_change
number format: float
nullable
bounce_rate

Session-weighted bounce rate, percent (0-100).

number format: float
nullable
bounce_rate_change
number format: float
nullable
average_session_duration

Session-weighted average session duration, in seconds.

number format: float
nullable
average_session_duration_change
number format: float
nullable
key_events
integer
nullable
key_events_change
number format: float
nullable
session_key_event_rate

Share of sessions with a key event, percent (0-100).

number format: float
nullable
session_key_event_rate_change
number format: float
nullable
gsc_insights

Returned only with include=gsc_insights. Google Search Console performance for the project — the same figures the Project List columns show. Average position is impression-weighted and CTR is recomputed from the clicks and impressions next to it, so the three always agree. Each metric is followed by its *_change: the relative change against comparison_period in percent. For average_position a negative change means the position improved.

object
status

Whether the block holds data: ‘ok’ — data for the period; ‘no_data’ — the source is set up but stored nothing for the period; ‘not_connected’ — the project has no such integration. Every metric is null unless the status is ok, so a null is never confused with a real zero.

string
Allowed values: ok no_data not_connected
period

Date range a metric block was computed for, inclusive. Null when the project has no stored aggregate yet.

object
date_from
string format: date
date_to
string format: date
comparison_period

Date range a metric block was computed for, inclusive. Null when the project has no stored aggregate yet.

object
date_from
string format: date
date_to
string format: date
clicks
integer
nullable
clicks_change
number format: float
nullable
impressions
integer
nullable
impressions_change
number format: float
nullable
ctr

Clicks / impressions, percent (0-100).

number format: float
nullable
ctr_change
number format: float
nullable
average_position

Impression-weighted average position.

number format: float
nullable
average_position_change
number format: float
nullable
ranked_pages

Distinct pages with impressions in the period.

integer
nullable
ranked_pages_change
number format: float
nullable
ranked_keywords

Distinct search queries with impressions in the period.

integer
nullable
ranked_keywords_change
number format: float
nullable
rank_tracker

Returned only with include=rank_tracker. Latest ranking snapshot of the tracked keywords — the Rank Tracker columns of the Project List. This block is a snapshot, not a period aggregate: it carries as_of_date instead of period/comparison_period and exposes no change metrics. Rank Tracker has no external integration, so the only non-ok status is ‘no_data’ (no snapshot in the last 30 days, e.g. a project without tracked keywords). Position buckets do not overlap.

object
status

Whether the block holds data: ‘ok’ — data for the period; ‘no_data’ — the source is set up but stored nothing for the period; ‘not_connected’ — the project has no such integration. Every metric is null unless the status is ok, so a null is never confused with a real zero.

string
Allowed values: ok no_data not_connected
as_of_date

Day the snapshot was taken.

string format: date
nullable
visibility

Visibility score of the tracked keyword set, percent (0-100).

number format: float
nullable
top_1

Keywords ranked in position 1.

integer
nullable
top_3

Keywords ranked in positions 2-3.

integer
nullable
top_10

Keywords ranked in positions 4-10.

integer
nullable
top_100

Keywords ranked in positions 11-100.

integer
nullable
ai_visibility

Returned only with include=ai_visibility. AI Visibility state of the project. brand_visibility and citation_share are the Project List figures: a rolling 30-day aggregate over the tracked prompts ending on as_of_date, which is why they carry no change metrics. status is ‘not_connected’ when the project has no active AI prompts. AI traffic is reported separately under ai_traffic, with its own status and periods, because it comes from GA4 rather than from prompt runs.

object
status

Whether the block holds data: ‘ok’ — data for the period; ‘no_data’ — the source is set up but stored nothing for the period; ‘not_connected’ — the project has no such integration. Every metric is null unless the status is ok, so a null is never confused with a real zero.

string
Allowed values: ok no_data not_connected
as_of_date

Last day of the stored 30-day prompt aggregate.

string format: date
nullable
brand_visibility

Share of prompt runs mentioning the brand, percent (0-100).

number format: float
nullable
citation_share

Share of citations pointing to the project, percent (0-100).

number format: float
nullable
ai_traffic

AI chat traffic of the project, aggregated across every AI source from the stored AI-chat GA4 data. Requires a connected GA4 property. Note: bounce_rate is a percentage here, while ai-visibility/ai_traffic_summary returns the same metric as a 0-1 fraction.

object
status

Whether the block holds data: ‘ok’ — data for the period; ‘no_data’ — the source is set up but stored nothing for the period; ‘not_connected’ — the project has no such integration. Every metric is null unless the status is ok, so a null is never confused with a real zero.

string
Allowed values: ok no_data not_connected
period

Date range a metric block was computed for, inclusive. Null when the project has no stored aggregate yet.

object
date_from
string format: date
date_to
string format: date
comparison_period

Date range a metric block was computed for, inclusive. Null when the project has no stored aggregate yet.

object
date_from
string format: date
date_to
string format: date
ai_chat_sessions
integer
nullable
ai_chat_sessions_change
number format: float
nullable
key_events
integer
nullable
key_events_change
number format: float
nullable
session_key_event_rate

Key events per session, percent.

number format: float
nullable
session_key_event_rate_change
number format: float
nullable
bounce_rate

Session-weighted bounce rate, percent (0-100).

number format: float
nullable
bounce_rate_change
number format: float
nullable
average_session_duration

Session-weighted average session duration, in seconds.

number format: float
nullable
average_session_duration_change
number format: float
nullable
tracked_keywords

One row per keyword × geo pair created with the project. Empty when no keywords were sent.

Array<object>

One keyword tracked in one geo. tracked_keyword_id is the id used by GET /api/v1/keywords and by DELETE /api/v1/keywords.

object
tracked_keyword_id

ID of the tracked keyword: one keyword in one geo. Pass it to GET /api/v1/keywords, GET /api/v1/keyword_daily_positions, GET /api/v1/serp_snapshot and DELETE /api/v1/keywords.

integer
keyword

Keyword as stored: trimmed and lower-cased.

string
search_engine
string
Allowed values: google bing yahoo
device
string
Allowed values: desktop mobile
country_code
string
country_name
string
language_code
string
language_name
string
location_id

Opaque location id; null when the whole country is tracked.

string
nullable
location_name

Canonical Google location name; null when the whole country is tracked.

string
nullable
Example
{
"data": {
"project_id": 12345,
"project_name": "Example",
"url": "https://example.com",
"domain_scope": {
"protocols": [
"http",
"https"
],
"scope_type": "subdomains",
"path": "/"
},
"site_audit_enabled": false,
"last_crawl_date": null,
"last_crawl_status": null,
"tracked_keywords": [
{
"tracked_keyword_id": 987654,
"keyword": "seo audit",
"search_engine": "google",
"device": "desktop",
"country_code": "US",
"country_name": "United States",
"language_code": "en",
"language_name": "English",
"location_id": null,
"location_name": null,
"created": true
}
]
}
}

Missing or invalid API key

Media typeapplication/json

Returned as INVALID_API_KEY when the key is missing or unknown, and as REVOKED_API_KEY when the key exists but was revoked — the latter needs a new key.

object
error
required
object
code
required
string
Allowed values: VALIDATION_ERROR BAD_REQUEST PROJECT_NOT_FOUND SEGMENT_NOT_FOUND ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY ACCOUNT_BLOCKED ACCOUNT_INACTIVE RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS INTERNAL_ERROR CRAWL_NOT_FOUND INVALID_DATE_RANGE INVALID_FILTER INVALID_EVENT_TYPE KEYWORD_NOT_FOUND OPPORTUNITY_NOT_FOUND SNAPSHOT_UNAVAILABLE GSC_NOT_CONNECTED GA4_NOT_CONNECTED SITE_AUDIT_DATA_UNAVAILABLE GA4_DATA_UNAVAILABLE UNSUPPORTED_FILTER UNSUPPORTED_DIMENSION UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE QUOTA_EXCEEDED
message
required
string
Example
{
"error": {
"code": "INVALID_API_KEY",
"message": "Invalid or missing API key."
}
}

No active API entitlement, or the project or keyword limit of the plan is reached

Media typeapplication/json
One of:

Returned as MISSING_PUBLIC_API_ACCESS when the account has no active API entitlement, as ACCESS_DENIED when the project is shared with the account at an access level that does not allow this request (a project of another account is reported as 404 PROJECT_NOT_FOUND instead), and as ACCOUNT_BLOCKED or ACCOUNT_INACTIVE when the account behind a valid key is blocked or deactivated — a new key will not help, contact support@sitechecker.pro.

object
error
required
object
code
required
string
Allowed values: VALIDATION_ERROR BAD_REQUEST PROJECT_NOT_FOUND SEGMENT_NOT_FOUND ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY ACCOUNT_BLOCKED ACCOUNT_INACTIVE RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS INTERNAL_ERROR CRAWL_NOT_FOUND INVALID_DATE_RANGE INVALID_FILTER INVALID_EVENT_TYPE KEYWORD_NOT_FOUND OPPORTUNITY_NOT_FOUND SNAPSHOT_UNAVAILABLE GSC_NOT_CONNECTED GA4_NOT_CONNECTED SITE_AUDIT_DATA_UNAVAILABLE GA4_DATA_UNAVAILABLE UNSUPPORTED_FILTER UNSUPPORTED_DIMENSION UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE QUOTA_EXCEEDED
message
required
string
Example
{
"error": {
"code": "MISSING_PUBLIC_API_ACCESS",
"message": "API access is not available: the account has no active API entitlement."
}
}

Invalid request body

Media typeapplication/json

Rejected query parameters. error.code is VALIDATION_ERROR for parameter validation (including a query parameter the endpoint does not accept), or INVALID_DATE_RANGE / INVALID_FILTER / INVALID_EVENT_TYPE / UNSUPPORTED_FILTER / UNSUPPORTED_DIMENSION / UNSUPPORTED_METRIC / UNSUPPORTED_SCOPE / SEGMENT_FILTER_UNSUPPORTED for module-specific rules. Request-body validation errors also carry error.details, listing every invalid field.

object
error
required
object
code
required
string
Allowed values: VALIDATION_ERROR BAD_REQUEST PROJECT_NOT_FOUND SEGMENT_NOT_FOUND ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY ACCOUNT_BLOCKED ACCOUNT_INACTIVE RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS INTERNAL_ERROR CRAWL_NOT_FOUND INVALID_DATE_RANGE INVALID_FILTER INVALID_EVENT_TYPE KEYWORD_NOT_FOUND OPPORTUNITY_NOT_FOUND SNAPSHOT_UNAVAILABLE GSC_NOT_CONNECTED GA4_NOT_CONNECTED SITE_AUDIT_DATA_UNAVAILABLE GA4_DATA_UNAVAILABLE UNSUPPORTED_FILTER UNSUPPORTED_DIMENSION UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE QUOTA_EXCEEDED
message
required
string
error
required
object
details

Every invalid field, not only the first one repeated in error.message. Present on request-body validation errors; field is the path inside the body.

Array<object>
object
field
required

Path of the invalid field inside the request body, e.g. url, keywords[0], geos[1].country_code.

string
message
required
string
Example
{
"error": {
"code": "VALIDATION_ERROR",
"message": "project_id is required."
}
}

Rate limit exceeded — retry after the interval in the Retry-After header

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: VALIDATION_ERROR BAD_REQUEST PROJECT_NOT_FOUND SEGMENT_NOT_FOUND ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY ACCOUNT_BLOCKED ACCOUNT_INACTIVE RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS INTERNAL_ERROR CRAWL_NOT_FOUND INVALID_DATE_RANGE INVALID_FILTER INVALID_EVENT_TYPE KEYWORD_NOT_FOUND OPPORTUNITY_NOT_FOUND SNAPSHOT_UNAVAILABLE GSC_NOT_CONNECTED GA4_NOT_CONNECTED SITE_AUDIT_DATA_UNAVAILABLE GA4_DATA_UNAVAILABLE UNSUPPORTED_FILTER UNSUPPORTED_DIMENSION UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE QUOTA_EXCEEDED
message
required
string
Example
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again later."
}
}

Internal server error

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: VALIDATION_ERROR BAD_REQUEST PROJECT_NOT_FOUND SEGMENT_NOT_FOUND ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY ACCOUNT_BLOCKED ACCOUNT_INACTIVE RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS INTERNAL_ERROR CRAWL_NOT_FOUND INVALID_DATE_RANGE INVALID_FILTER INVALID_EVENT_TYPE KEYWORD_NOT_FOUND OPPORTUNITY_NOT_FOUND SNAPSHOT_UNAVAILABLE GSC_NOT_CONNECTED GA4_NOT_CONNECTED SITE_AUDIT_DATA_UNAVAILABLE GA4_DATA_UNAVAILABLE UNSUPPORTED_FILTER UNSUPPORTED_DIMENSION UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE QUOTA_EXCEEDED
message
required
string
Example
{
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error."
}
}