API reference
Account
Management API: GET /me/context
Call this first when the user is new, has no site yet, or asks how to start (especially for building their own frontend). Returns the account's headless beta state, the sites it owns with their frontend mode, the journey stage, the next step (who does it, link or capability) and guidance. While headlessBeta.status is PENDING, only explain the wait: do not create sites, collections or integration code. For an existing site call sites.context instead. Errors: UNAUTHORIZED, FORBIDDEN (service-account tokens belong to one site: call sites.context).
Response 200
headlessBetaobjectrequiredheadlessBeta.gatedbooleanrequiredtrue while building your own frontend (headless) is in beta by invitation; false once it is open to every account.
headlessBeta.status"NONE" | "PENDING" | "APPROVED" | "REJECTED" | "REVOKED"requiredThis account's beta state: NONE (not applied), PENDING (waiting for an invitation), APPROVED (invited), REJECTED (not invited this time), REVOKED (partnership ended).
headlessBeta.canApplybooleanrequiredheadlessBeta.canCreateSitebooleanrequiredWhether sites.create with frontendMode HEADLESS will succeed for this account.
headlessBeta.userVisibleReasonstring | nullrequiredReason given when status is REJECTED; null otherwise.
headlessBeta.reapplyAfterstring | nullrequiredISO time after which a rejected account may apply again; null when not in cooldown.
headlessBeta.contactstring | nullrequiredContact channel the user left on the application (e.g. email), without the handle.
headlessBeta.reviewSlaWorkingDaysintegerrequiredHow many working days we usually take to reply to an application.
headlessBeta.applyUrlstringrequiredBackoffice link to the apply / create card.
sitesobject[]requiredsites[].websiteIdstringrequiredsites[].namestringrequiredsites[].frontendMode"HOSTED" | "HEADLESS"requiredsites[].serviceState"active" | "unpublished" | "closed"requiredWhether the public APIs serve this site right now.
sites[].systemHoststring | nullrequiredsites[].externalStorefrontUrlstring | nullrequiredtokenCanCreateSitesbooleanrequiredfalse when this token is restricted to specific websites; sites.create then fails with TOKEN_WEBSITE_SCOPED. The user either creates the site in the backoffice, or switches this connection to all websites under Account settings > API access (no reconnection needed); see guidance.
stage"needs_account" | "can_apply" | "pending" | "rejected_cooldown" | "revoked" | "ready_to_create" | "has_headless_site" | "deployed"requiredWhere the account is on the path to a custom-frontend site.
nextStepobject | nullrequirednextStep.id"apply" | "awaitInvite" | "createSite"requirednextStep.who"user" | "agent" | "either"requiredWho can do this step: the user only, the agent, or either.
nextStep.urlstring | nullrequiredBackoffice link the user can open for this step.
nextStep.capabilitystring | nullrequiredCapability the agent may call for this step; null when only the user can act.
guidancestring[]requiredWhat to do and say now. Follow it; speak to the user in their language, one step at a time.
Errors
UNAUTHORIZED401FORBIDDEN403 · service-account tokens belong to one site: call sites.context
MCP tool account_context
curl -X GET "https://app.kanorio.com/api/v1/me/context" \ -H "Authorization: Bearer $KANORIO_TOKEN"
{
"headlessBeta": {
"gated": true,
"status": "NONE",
"canApply": true,
"canCreateSite": false,
"userVisibleReason": null,
"reapplyAfter": null,
"contact": null,
"reviewSlaWorkingDays": 3,
"applyUrl": "https://app.kanorio.com/site/new?kind=headless"
},
"sites": [],
"tokenCanCreateSites": true,
"stage": "can_apply",
"nextStep": {
"id": "apply",
"who": "either",
"url": "https://app.kanorio.com/site/new?kind=headless",
"capability": "headless.request_access"
},
"guidance": [
"Headless is in beta by invitation. Offer to submit the application with `headless_request_access`, but ask the user each question first and wait for their answers. Never infer or auto-fill any field."
]
}