{"openapi":"3.1.0","info":{"title":"Pluma API","version":"1","description":"Headless CMS for agents. Docs for humans: https://pluma.so/docs/api/index · For agents: https://pluma.so/llms.txt"},"servers":[{"url":"https://pluma.so"}],"security":[{"bearer":[]}],"paths":{"/api/v1":{"get":{"operationId":"root","summary":"What this is, what your key can do, and where to go next","responses":{"200":{"description":"Root","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Root"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}":{"get":{"operationId":"getSpace","summary":"Site","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"responses":{"200":{"description":"Site","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Space"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateSite","summary":"Set the live and staging URLs (manage_webhooks)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"production_url":{"type":"string","description":"Like https://www.example.com. Empty clears it"},"preview_url":{"type":"string","description":"Like https://staging.example.com. Empty clears it"}}}}}},"responses":{"200":{"description":"Site","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Space"},{"type":"object","properties":{"warnings":{"type":"array","items":{"type":"string"},"description":"What is set up halfway, like a staging URL without a staging hook"}}}]}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/answers":{"get":{"operationId":"getAnswers","summary":"What ChatGPT answers to the site's questions (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"responses":{"200":{"description":"Questions and the last run","content":{"application/json":{"schema":{"type":"object","properties":{"questions":{"type":"array","items":{"type":"object"}},"market":{"type":"object"},"run":{"type":["object","null"]},"history":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/questions":{"patch":{"operationId":"updateQuestions","summary":"Replace the questions asked to ChatGPT every week (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["questions"],"properties":{"questions":{"type":"array","minItems":1,"maxItems":30,"items":{"type":"string","maxLength":200}},"market":{"type":"object","properties":{"country":{"type":"string"},"city":{"type":"string"}}}}}}}},"responses":{"200":{"description":"The new list","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/analytics":{"get":{"operationId":"getAnalytics","summary":"The site's first-party analytics for the last N days (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":365,"default":30}}],"responses":{"200":{"description":"Analytics","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer"},"visitors":{"type":"integer"},"page_views":{"type":"integer"},"from_ai":{"type":"object"},"sources":{"type":"array","items":{"type":"object"}},"crawlers":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/search_queries":{"get":{"operationId":"getSearchQueries","summary":"Top Google and Bing searches and pages, from Search Console and Bing Webmaster Tools (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"engine","in":"query","required":false,"schema":{"type":"string","enum":["google","bing"]},"description":"Only one engine. Both by default"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":28}}],"responses":{"200":{"description":"Search queries","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer"},"since":{"type":"string","format":"date"},"connections":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"site_url":{"type":"string"},"synced_at":{"type":["string","null"]},"last_error":{"type":["string","null"]}}}},"totals":{"type":"object"},"queries":{"type":"array","items":{"$ref":"#/components/schemas/SearchRow"}},"pages":{"type":"array","items":{"$ref":"#/components/schemas/SearchRow"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/readiness":{"get":{"operationId":"getReadiness","summary":"The last AI readiness check of the live site (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"responses":{"200":{"description":"Last check","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessCheck"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"checkReadiness","summary":"Read the live site like an AI crawler and run the checks (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"responses":{"201":{"description":"New check","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessCheck"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/export":{"get":{"operationId":"exportSpace","summary":"The whole site in one JSON (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"responses":{"200":{"description":"Export","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/content_types":{"get":{"operationId":"listContentTypes","summary":"Content types","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentTypeCollection"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createContentType","summary":"Create a content type (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"true = saves nothing, returns what would be created"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentTypeInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentType"}}}},"200":{"description":"dry_run","content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean"},"would_create":{"$ref":"#/components/schemas/ContentType"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/content_types/{id}":{"get":{"operationId":"getContentType","summary":"One content type","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"API ID"}],"responses":{"200":{"description":"Content type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentType"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateContentType","summary":"Edit the name, description, or title field (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"API ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"display_field":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentType"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/content_types/{content_type_id}/fields":{"post":{"operationId":"createField","summary":"Add a field (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"content_type_id","in":"path","required":true,"schema":{"type":"string"},"description":"Content type API ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldInput"}}}},"responses":{"201":{"description":"Content type with the new field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentType"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/content_types/{content_type_id}/fields/{id}":{"patch":{"operationId":"updateField","summary":"Edit or hide a field (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"content_type_id","in":"path","required":true,"schema":{"type":"string"},"description":"Content type API ID"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Field API ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"},"localized":{"type":"boolean"},"hidden":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Content type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentType"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/entries":{"get":{"operationId":"listEntries","summary":"Entries (published ones with a delivery key, latest version with preview/management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"content_type","in":"query","required":false,"schema":{"type":"string"},"description":"Only entries of that type"},{"name":"order","in":"query","required":false,"schema":{"type":"string"},"description":"sys.created_at, sys.updated_at, sys.published_at, or fields.<api_id>; a leading - sorts descending"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"1 to 1000, default 100"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer"},"description":"How many to skip"},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Locale, or * for all"},{"name":"rich_text","in":"query","required":false,"schema":{"type":"string"},"description":"json (default), markdown, or html"},{"name":"include","in":"query","required":false,"schema":{"type":"integer"},"description":"0, 1, or 2 levels of references"},{"name":"fields.<api_id>","in":"query","required":false,"schema":{"type":"string"},"description":"Equal to that value (requires content_type)"}],"responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntryCollection"}}}},"304":{"description":"Not modified (If-None-Match)"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createEntry","summary":"Create a draft entry (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content_type","fields"],"properties":{"content_type":{"type":"string"},"fields":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/entries/{id}":{"get":{"operationId":"getEntry","summary":"One entry","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Entry ID"},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Locale"},{"name":"rich_text","in":"query","required":false,"schema":{"type":"string"},"description":"json, markdown, or html"},{"name":"include","in":"query","required":false,"schema":{"type":"integer"},"description":"0 to 2"}],"responses":{"200":{"description":"Entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateEntry","summary":"Edit fields; version keeps you from overwriting changes (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Entry ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"integer"},"fields":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/entries/{id}/publish":{"post":{"operationId":"publishEntry","summary":"Publish (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Entry ID"}],"responses":{"200":{"description":"Entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/entries/{id}/archive":{"post":{"operationId":"archiveEntry","summary":"Archive (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Entry ID"}],"responses":{"200":{"description":"Entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/entries/{id}/unarchive":{"post":{"operationId":"unarchiveEntry","summary":"Unarchive (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Entry ID"}],"responses":{"200":{"description":"Entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/entries/{id}/versions":{"get":{"operationId":"listEntryVersions","summary":"Version history (preview or management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Entry ID"}],"responses":{"200":{"description":"Versions","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"items":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/assets":{"get":{"operationId":"listAssets","summary":"Files","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"1 to 1000"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetCollection"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"uploadAsset","summary":"Upload a file with multipart, or from a URL with JSON (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"title":{"type":"string"},"alt":{"type":"string"},"description":{"type":"string"}}}},"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"https and on the public internet; Pluma downloads the file"},"filename":{"type":"string"},"title":{"type":"string"},"alt":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/assets/{id}":{"get":{"operationId":"getAsset","summary":"One file","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"File ID"}],"responses":{"200":{"description":"File","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateAsset","summary":"Edit the title, alt text, or description (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"File ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"alt":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri","description":"Replace the file with the one at this https URL (same id)"},"filename":{"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Replace the file (same id)"},"title":{"type":"string"},"alt":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"File","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/batch":{"post":{"operationId":"batch","summary":"Several operations in one request, all or nothing (management)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"Validates everything without saving anything"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["operations"],"properties":{"operations":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/BatchOperation"}}}}}}},"responses":{"200":{"description":"One result per operation, in the same order","content":{"application/json":{"schema":{"type":"object","required":["dry_run","total","results"],"properties":{"dry_run":{"type":"boolean"},"total":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/BatchResult"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/join/{token}":{"get":{"operationId":"readInvite","summary":"Read the invite (markdown for the agent, no key needed)","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"The token from the invite link"}],"responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"}}}},"/join/{token}/redeem":{"post":{"operationId":"redeemInvite","summary":"Redeem the invite and get the agent token","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"The token from the invite link"}],"responses":{"201":{"description":"Agent token (shown once)","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"agent":{"type":"object"},"space":{"type":"string"},"next":{"type":"array","items":{"type":"string"}}}}}}},"404":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/llms.txt":{"get":{"operationId":"getSpaceDocs","summary":"The site docs: content model, locales, and endpoints","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/api_keys":{"get":{"operationId":"listApiKeys","summary":"Active keys for the site (manage_keys)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createApiKey","summary":"Create a delivery or preview key (manage_keys)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug","example":"acton-estero"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","kind"],"properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["delivery","preview"]}}}}}},"responses":{"201":{"description":"Token (shown once)","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"key":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/mcp":{"post":{"operationId":"mcp","summary":"MCP server (JSON-RPC 2.0, stateless Streamable HTTP). See /docs/mcp/index","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"JSON-RPC message: initialize, tools/list, tools/call"}}}},"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"protectedResourceMetadata","summary":"Protected resource metadata (RFC 9728)","security":[],"responses":{"200":{"description":"Metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/oauth-protected-resource/mcp":{"get":{"operationId":"protectedResourceMetadataMcp","summary":"Metadata for the /mcp resource (RFC 9728)","security":[],"responses":{"200":{"description":"Metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"operationId":"authorizationServerMetadata","summary":"Authorization server metadata (RFC 8414)","security":[],"responses":{"200":{"description":"Metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/oauth/register":{"post":{"operationId":"registerClient","summary":"Dynamic client registration (RFC 7591)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["redirect_uris"],"properties":{"client_name":{"type":"string"},"redirect_uris":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Client registered","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"OAuth error: { error, error_description }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}}}}},"/oauth/authorize":{"get":{"operationId":"authorize","summary":"Consent screen (HTML, requires a session)","security":[],"parameters":[{"name":"response_type","in":"query","required":true,"schema":{"type":"string"}},{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string"}},{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","required":true,"schema":{"type":"string"}},{"name":"resource","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"HTML"},"302":{"description":"Redirects to login if there is no session"},"400":{"description":"Invalid request (HTML)"}}},"post":{"operationId":"authorizeDecision","summary":"Approve or cancel (the form on the screen)","security":[],"responses":{"302":{"description":"Goes back to redirect_uri with code or error"}}}},"/oauth/token":{"post":{"operationId":"token","summary":"Exchange the code for the token (PKCE S256)","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","code","redirect_uri","client_id","code_verifier"],"properties":{"grant_type":{"type":"string"},"code":{"type":"string"},"redirect_uri":{"type":"string"},"client_id":{"type":"string"},"code_verifier":{"type":"string"}}}}}},"responses":{"200":{"description":"{ access_token, token_type, scope }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"OAuth error: { error, error_description }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}}}}},"/api/v1/spaces/{space_id}/webhooks":{"get":{"operationId":"listWebhooks","summary":"Deploy hooks (manage_webhooks)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug"}],"responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createWebhook","summary":"Create a deploy hook; returns the secret once (manage_webhooks)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","kind","url"],"properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["netlify","vercel","generic"]},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["entry.published","entry.unpublished","content_type.changed","entry.saved","asset.replaced"]}},"target":{"type":"string","enum":["production","preview"],"description":"production rebuilds the live site on publish; preview also rebuilds on every save (entry.saved)"}}}}}},"responses":{"201":{"description":"{ webhook, secret }","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Delete a deploy hook (manage_webhooks)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"}],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/spaces/{space_id}/webhooks/{id}/test":{"post":{"operationId":"testWebhook","summary":"Send a test hook right now (manage_webhooks)","parameters":[{"name":"space_id","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"}],"responses":{"200":{"description":"{ delivery }","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Pluma key (pluma_dlv_, pluma_prv_, pluma_mgt_) or agent token (pluma_agt_)"}},"responses":{"Error":{"description":"Error, with how to fix it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"SearchRow":{"type":"object","properties":{"engine":{"type":"string","enum":["google","bing"]},"query":{"type":"string"},"page":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":"number"},"position":{"type":["number","null"]}}},"ReadinessCheck":{"type":"object","properties":{"url":{"type":"string"},"checked_at":{"type":"string","format":"date-time"},"passed":{"type":"integer"},"total":{"type":"integer"},"checks":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["pass","warn","fail"]},"detail":{"type":"string"},"fix_by":{"type":"string","enum":["content","site"]},"ask_agent":{"type":["string","null"]},"doc_url":{"type":"string"}}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","fix","doc_url"],"properties":{"code":{"type":"string","enum":["missing_key","invalid_key","wrong_space","key_cannot","not_found","invalid_parameter","validation_failed","version_conflict","invalid_body","invite_used","invite_expired","rate_limited","check_unavailable"]},"message":{"type":"string"},"fix":{"type":"string"},"doc_url":{"type":"string","format":"uri"},"details":{"type":"object"}}}}},"BatchOperation":{"type":"object","required":["op"],"properties":{"op":{"type":"string","description":"create_entry, update_entry, create_asset, publish_entry, archive_entry, or unarchive_entry"},"ref":{"type":"string","description":"A name to use later as \"$name\" in id and in reference or file fields"},"id":{"type":"string","description":"Entry ID, or \"$ref\" from an earlier operation"},"content_type":{"type":"string"},"fields":{"type":"object","additionalProperties":true},"version":{"type":"integer"},"url":{"type":"string","format":"uri"},"data":{"type":"string","description":"A local file for create_asset, in base64, together with filename"},"filename":{"type":"string"},"title":{"type":"string"},"alt":{"type":"string"},"description":{"type":"string"}}},"BatchResult":{"type":"object","required":["op","sys"],"properties":{"op":{"type":"string"},"ref":{"type":"string"},"sys":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"content_type":{"type":"string"},"version":{"type":"integer"},"status":{"type":"string"},"url":{"type":"string","format":"uri"},"preview_url":{"type":"string","format":"uri"}}}}},"Root":{"type":"object","properties":{"name":{"type":"string"},"about":{"type":"string"},"docs":{"type":"string"},"key":{"type":"object","properties":{"kind":{"type":"string","enum":["delivery","preview","management"]},"name":{"type":"string"},"space":{"type":"string"},"can":{"type":"array","items":{"type":"string"}}}},"next":{"type":"string"}}},"Space":{"type":"object","properties":{"sys":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"Space"}}},"name":{"type":"string"},"default_locale":{"type":"string"},"production_url":{"type":["string","null"]},"preview_url":{"type":["string","null"]},"locales":{"type":"array","items":{"type":"object"}},"content_types":{"type":"array","items":{"type":"object","properties":{"api_id":{"type":"string"},"name":{"type":"string"}}}}}},"Field":{"type":"object","properties":{"api_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["symbol","text","rich_text","integer","number","boolean","date","json","slug","tags","reference","references","asset","assets","list"]},"required":{"type":"boolean"},"localized":{"type":"boolean"},"link_content_types":{"type":"array","items":{"type":"string"}},"item_fields":{"type":"array","description":"For type list, the fields of each row","items":{"type":"object","properties":{"api_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["symbol","text","integer","number","boolean","date"]}}}},"help":{"type":"string","description":"One line for whoever enters content (format, unit, or example)"}}},"FieldInput":{"allOf":[{"$ref":"#/components/schemas/Field"}],"required":["api_id","name","type"]},"ContentType":{"type":"object","properties":{"sys":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"ContentType"}}},"name":{"type":"string"},"description":{"type":["string","null"]},"singleton":{"type":"boolean"},"display_field":{"type":["string","null"]},"url_path":{"type":["string","null"],"description":"Where its entries live on the site, like /blog/{slug}"},"guidance":{"type":"string","description":"When to use this type and when not to. Only present if the type has it"},"previews":{"type":"array","description":"Previews of how it looks on the site. Only present if the type has them","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"alt":{"type":["string","null"]}}}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/Field"}}}},"ContentTypeInput":{"type":"object","required":["name","api_id"],"properties":{"name":{"type":"string"},"api_id":{"type":"string"},"description":{"type":"string"},"singleton":{"type":"boolean"},"display_field":{"type":"string"},"url_path":{"type":"string"},"guidance":{"type":"string","maxLength":2000},"previews":{"type":"array","maxItems":4,"description":"Image file IDs","items":{"type":"string"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldInput"}}}},"Link":{"type":"object","properties":{"sys":{"type":"object","properties":{"type":{"const":"Link"},"link_type":{"type":"string","enum":["Entry","Asset"]},"id":{"type":"string"}}}}},"Entry":{"type":"object","properties":{"sys":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"Entry"},"content_type":{"type":"string"},"version":{"type":"integer"},"published_version":{"type":["integer","null"]},"status":{"type":"string","enum":["draft","published","changed","archived"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"},"locale":{"type":"string"},"url":{"type":"string","format":"uri","description":"Where it lives on the live site. Only when published and the site's production_url and the type's url_path are set"},"preview_url":{"type":"string","format":"uri","description":"Where it shows on the staging site. Only with a key that reads drafts, and when preview_url and url_path are set"}}},"fields":{"type":"object","additionalProperties":true,"description":"Your fields by API ID. References and files come as Link."}}},"Asset":{"type":"object","properties":{"sys":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"Asset"}}},"fields":{"type":"object","properties":{"title":{"type":"string"},"alt":{"type":["string","null"]},"description":{"type":["string","null"]},"file":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"filename":{"type":"string"},"content_type":{"type":"string"},"size":{"type":"integer"},"width":{"type":"integer"},"height":{"type":"integer"}}}}}}},"EntryCollection":{"type":"object","properties":{"sys":{"type":"object","properties":{"type":{"const":"Array"}}},"total":{"type":"integer"},"skip":{"type":"integer"},"limit":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}},"includes":{"type":"object","properties":{"Entry":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}},"Asset":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}}}}},"AssetCollection":{"type":"object","properties":{"sys":{"type":"object","properties":{"type":{"const":"Array"}}},"total":{"type":"integer"},"skip":{"type":"integer"},"limit":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"includes":{"type":"object","properties":{"Entry":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}},"Asset":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}}}}},"ContentTypeCollection":{"type":"object","properties":{"sys":{"type":"object","properties":{"type":{"const":"Array"}}},"total":{"type":"integer"},"skip":{"type":"integer"},"limit":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentType"}},"includes":{"type":"object","properties":{"Entry":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}},"Asset":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}}}}}}}}