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.
- 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.
- Set code_challenge to the SHA-256 digest of the verifier, encoded as base64url with the padding removed. Set code_challenge_method to S256.
- 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