Arc

API docs

Connect with Arc

Create a custom app integration and use Arc in your workflows. Read reports and queue runs with an API key or a connected app.

Connect

Use an API key, or connect an app with the OAuth 2.1 authorization code flow and PKCE.

API key

A studio owner or admin creates a key in Arc. Send it as a bearer token. Use a key when the caller can store a secret and nobody needs to approve a browser prompt. The same key works on the API host and the MCP host. The secret is shown once.

Authorization code with PKCE

Use this when you ship an app or plugin that a person connects to their studio. Arc issues a public client id (arc_app_...). There is no client secret, same as a public OAuth client on other platforms. PKCE (Proof Key for Code Exchange) replaces that secret. Your server creates a verifier, the browser sends only a hash of it, and the token request must present the original verifier. Arc accepts S256 only.

  1. Create a code_verifier of 43 to 128 characters from A-Z, a-z, 0-9, hyphen, period, underscore, and tilde. Store it on your server with a random state value.
  2. Set code_challenge to the SHA-256 digest of the verifier, encoded as base64url with the padding removed. Set code_challenge_method to S256.
  3. Send the browser to the authorize URL below. The verifier never goes in that URL.

Authorize URL

Open this on the portal. resource is required and chooses the audience of the token: the API host for REST, or the MCP host for an agent. A token for one host is rejected on the other.

  • response_typeMust be code.
  • client_idThe issued id, arc_app_.... An unknown id is rejected.
  • redirect_uriExact callback. https on a public hostname, or http://localhost or http://127.0.0.1 on any port. No userinfo, no fragment, no raw IP, no .local.
  • code_challengeThe S256 challenge. Not the verifier.
  • code_challenge_methodS256. Plain is rejected.
  • resourceCanonical API URL, or the canonical MCP URL. Required on authorize and on the token request.
  • scopearc:read, and arc:enqueue if this app will queue runs. Projects and services are chosen on the consent page, not in this string.
  • stateThe random value you stored. Compare it on the way back.
  • site_originOptional. The install home URL. Not a scope. When present, the page pairs an existing site or creates one. www and the bare host are different sites.
  • site_nameOptional. Prefills the site title. The person can edit it.

What the person approves

If they are signed out, Arc uses magic-link sign-in and returns them to the same URL. They must be a studio owner or admin. They pick the studio, the projects this app may read, and the services. If you sent site_origin, they pair a matching site or create one on this page. That create does not spend an API credit, and the app does not call a create-site route afterwards.

Approve redirects to your redirect_uri with code, state, and iss. iss is the portal origin. The code lasts 60 seconds and works once. Check state and iss before you exchange the code. Cancel redirects with error=access_denied, plus state and iss.

Exchange the code

Your server POSTs form fields to the portal token endpoint. Send the verifier here. Do not put tokens in the browser fragment.

access_token (arc_at_...) lasts 1 hour. refresh_token (arc_rt_...) lasts 30 days. token_type is Bearer. scope is what was granted. When this grant paired a site, site is included. Store it.

Refresh

Send the refresh token with the same client id and the same resource. Arc returns a new access token and a new refresh token. Sending a refresh token that was already rotated revokes that grant family.

Call the API

Send the access token as a bearer token, the same header as an API key. For an MCP agent Arc has not issued an id for, client_id is an HTTPS URL that hosts a client metadata document. An agent that can set a header can send an API key instead.

GET/v1/me

The calling credential, its scope, and the studio credit balance.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_me

Example

GET/v1/projects

Projects on this credential's allow-list.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_list_projects

Example

GET/v1/projects/{projectId}

One project, if it is on the allow-list.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_get_project

Example

GET/v1/projects/{projectId}/sites

Sites in a project on the allow-list.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_list_sites

Example

POST/v1/projects/{projectId}/sites

Create a site on an allow-listed project. Optional auto_run, auto_schedule, and auto_sitemap. The same normalized URL returns the existing site.

Body fields are name, baseUrl, and the optional booleans auto_run, auto_schedule, and auto_sitemap. A value that is not a boolean is rejected. Omitted or false skips auto_run and auto_schedule. auto_sitemap is accepted and does not skip the probe.

auto_run queues the first reports now. Analytics is left out until Google is connected and ready. The other granted services are queued together, with the same page split and daily report cap as Generate. The response includes runs. If that queue is refused, the site is not kept.

auto_schedule turns on the portal default clocks when the plan allows schedules: Analytics daily at 06:00, and every other granted service weekly at 06:00 on the weekday before create, in Europe/London. It does not turn on report email.

Every create probes for a sitemap when the project's sitemap discovery flag is open, before the crawl config is stored. The probe reads Sitemap: lines in robots.txt, then well-known paths, and stores a same-origin path when the body is a urlset or sitemapindex. The submitted origin is probed, including localhost and private addresses the operator named. Link-local addresses, cloud metadata names, a public name that resolves to those or to a private range, and any redirect off that origin are not fetched. A miss still creates the site. Without a sitemap or a longer target list, the first crawl is the homepage only. SEO, Accessibility, AI, and Security get engine config version 1 from that seed.

The create request spends 1 API credit. Queued crawls spend pages from the studio pool. The same normalized URL returns the existing site and does not queue, reschedule, or probe again.

Credits
1
Auth
Credential
Capability
enqueue
MCP tool
None

Idempotency-Key required

Example

POST/v1/projects/{projectId}/invite-status

Whether each email is a member of this project, has a pending invite, or neither.

Body is emails, at most 100. Each result is member, pending, or none for this project only. Pending means the invite can still be accepted. An expired invite is none. A person with an Arc login on another studio is none. The response has no user ids. This call spends 0 credits.

Credits
0
Auth
Credential
Capability
invite
MCP tool
arc_invite_status

Example

POST/v1/projects/{projectId}/invites

Email a project-member invite. The role is always project member.

One address uses email, and an optional continue path. continue must be an allowlisted portal path (/oauth/authorize?... or /connect/google?ticket=...). When it is set, the inbox link carries it as next so accept returns there. Success is 201 with invited true.

A list uses emails, at most 100, and no continue. One invalid address rejects the body. The response is 200 with results, one row per address: invited true, or invited false with a refusal code. A preview-denied address is a row. Seats and the pending cap are applied one address at a time, so the list cannot open more than the cap. One Idempotency-Key stores the whole result list. A mail failure is left out of that store. Addresses already sent come back as an open invite on a retry. The call spends one rate-limit token.

Idempotency-Key is required. Replay of the same key for the same credential returns the stored response and does not send again. A mail failure on a single address is not stored, so the same key can try that send again. The credential cannot choose a role. Accept stays the inbox link, which creates an account only after the person proves that inbox. Seats and the open-invite cap fail closed. An expired invite does not hold a seat or a pending slot. A paired install can invite only onto its own project. This call spends 0 credits.

Credits
0
Auth
Credential
Capability
invite
MCP tool
arc_create_invite

Idempotency-Key required

Example

POST/v1/sites/{siteId}/google-connect-handoffs

Mint a browser URL that connects Google for this site and returns to the caller.

Body is return_uri and an optional state. return_uri must be a safe https URL (or http on localhost) whose host is the site host or, for an OAuth grant, the host already consented on that grant. The response is url only. The bearer cannot set a Search Console site or a GA4 property. An OAuth grant can mint only for its paired site. An API key can mint for a site it can already read. The ticket lasts 24 hours, binds to the first Arc user who can access the project, and completes in the portal. This call spends 0 credits.

Credits
0
Auth
Credential
Capability
read
MCP tool
None

Example

GET/v1/sites/{siteId}

One site and the services this credential can read.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_get_site

Example

GET/v1/sites/{siteId}/runs

Audit runs for a site. Optional service filter.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_list_runs

Example

GET/v1/runs/{runId}

One audit run the credential can see.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_get_run

Example

GET/v1/runs/{runId}/media/{file}

One screenshot stored for a run the credential can read.

The file name is one path segment from that run's page screenshot. Spends 0 credits. A missing file is not found.

Credits
0
Auth
Credential
Capability
read
MCP tool
None

Example

POST/v1/runs/{runId}/media

Screenshots stored for a run the credential can read.

Body is files. Each name is one path segment, the same rule as a single screenshot. One call reads at most 40 names and returns at most 4 MB of raw image bytes. images lists file, contentType, and base64 data. missing lists names that are not stored or are not an image. remaining lists names not read because the name cap or the byte cap was reached. One missing file does not fail the call. Spends 0 credits and one rate-limit token.

Credits
0
Auth
Credential
Capability
read
MCP tool
None

Example

GET/v1/sites/{siteId}/scores

Latest succeeded score per in-scope service.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_get_scores

Example

GET/v1/sites/{siteId}/analytics

Visitor Analytics summary from the latest succeeded analytics run.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_get_analytics

Example

GET/v1/sites/{siteId}/reports/{service}

Report header and first section from the latest succeeded crawl run.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_get_report

Example

GET/v1/sites/{siteId}/reports/{service}/tables/{table}

One page of a report table from the latest succeeded crawl run.

table is pages, socials, or forms. page is 0-based. q searches that list. viewport filters accessibility pages. Spends 0 credits.

Credits
0
Auth
Credential
Capability
read
MCP tool
None

Example

GET/v1/sites/{siteId}/issues

Site issues. Optional service and state filters.

Credits
1
Auth
Credential
Capability
read
MCP tool
arc_list_issues

Example

GET/v1/catalog/{service}

Pinned public check catalog for one service.

Credits
0
Auth
Public
Capability
None
MCP tool
arc_get_catalog

Example

POST/v1/sites/{siteId}/runs

Queue one report, or several as one shared crawl. Spends 1 credit.

Credits
1
Auth
Credential
Capability
enqueue
MCP tool
arc_enqueue_run

Idempotency-Key required

Example

POST/v1/sites/{siteId}/reports/{service}/recrawl

Recrawl selected pages and update the current report. Spends 1 credit.

service is seo, a11y, or ai. Body is { urls }. URLs must already be on that report. Idempotency-Key is required. Reserves one page per URL. Does not count toward the daily run cap.

Credits
1
Auth
Credential
Capability
enqueue
MCP tool
arc_recrawl_pages

Idempotency-Key required

Example

POST/v1/sites/{siteId}/reports/{service}/fix

Continue a short crawl or fix the current SEO report. Spends 1 credit.

Body is {}. service is seo, a11y, ai, or security. A short crawl continues and reserves no pages. A finished SEO report recrawls unreadable pages, capped by the plan. Idempotency-Key is required. Does not count toward the daily run cap.

Credits
1
Auth
Credential
Capability
enqueue
MCP tool
arc_fix_report

Idempotency-Key required

Example

GET/v1/sites/{siteId}/seo-targets

Hash of the committed SEO keyphrases. No page list.

Returns hash, pageCount, and focusKeyphrase. The hash is SHA-256 over the focus line and one line per path. SEO must be in scope. Spends 1 credit.

Credits
1
Auth
Credential
Capability
read
MCP tool
None

Example

POST/v1/sites/{siteId}/seo-target-syncs

Start a session that stages SEO keyphrase changes.

Body is {}. Idempotency-Key is required. One open session per site. A new start abandons the previous uncommitted session. Spends 1 credit.

Credits
1
Auth
Credential
Capability
enqueue
MCP tool
None

Idempotency-Key required

Example

POST/v1/sites/{siteId}/seo-target-syncs/{syncId}/batches

Stage up to 500 keyphrase upserts and deletes.

Body is upserts and deletes. auto_run is rejected here. Idempotency-Key is required. A replay returns the stored response and does not write twice. Spends 1 credit.

Credits
1
Auth
Credential
Capability
enqueue
MCP tool
None

Idempotency-Key required

Example

POST/v1/sites/{siteId}/seo-target-syncs/{syncId}/commit

Write one SEO contract version from the staged rows.

Body is mode (patch or replace), baseHash, optional focusKeyphrase, optional recommendSchema, and auto_run. baseHash must match the current target or the call is 409 SYNC_CONFLICT and staging is discarded. recommendSchema true replaces expected schema types with the local recommendation. auto_run true queues SEO only and does not spend a second credit. A queue refusal keeps the contract. Spends 1 credit.

Credits
1
Auth
Credential
Capability
enqueue
MCP tool
None

Idempotency-Key required

Example

DELETE/v1/sites/{siteId}/seo-target-syncs/{syncId}

Discard a staged SEO keyphrase sync.

Idempotency-Key is required. Spends 1 credit. Does not change the committed target.

Credits
1
Auth
Credential
Capability
enqueue
MCP tool
None

Idempotency-Key required

Example

GET/v1/openapi.json

OpenAPI document generated from this registry.

Credits
0
Auth
Public
Capability
None
MCP tool
None

Example

GET/health

Process health. No credential.

Credits
0
Auth
Public
Capability
None
MCP tool
None

Example