Publish through API · MCP

Start with a publisher key

An operator issues publisher keys linked to an account. Keys in the same account share documents and idempotency records; each key still has its own read, write and publish scopes. Default keys can read, create and update drafts. Public release requires publish scope.

Account usage and limits

A default free account includes 100 accepted create, update and publish requests per UTC day, combined. Creating, updating and publishing one document uses three writes. Every key in the account and both API and MCP share this allowance.

Reads, identical idempotent retries and writes rejected before acceptance do not add usage. An accepted publication still uses one write if the engine fails or its response is lost; retrying that same operation adds no usage. Check used, remaining and the next UTC-midnight reset in resetsAt.

curl https://tera.wiki/api/v1/account/usage \
  -H "Authorization: Bearer $TERAWIKI_PUBLISHER_KEY"

Response: accountId, plan, dailyWriteLimit, used, remaining, resetsAt, upgradeRequired.

Ask an operator to upgrade the account for more capacity. Switching to upgraded increases capacity without resetting today’s usage. When the allowance is exhausted, check details.quota and upgradeRequired. A customer upgrade screen, billing and pricing are not available yet.

1. Submit a document

Send Markdown, a language, sources and author information. Save this payload as article.json, then use a key from your server environment.

{
  "locale": "en",
  "slug": "my-first-guide",
  "title": "My first document",
  "content": "## Overview\n\nThis example introduces publication through the TeraWiki API and MCP. Drafts remain private until a publisher key with publish scope explicitly releases them. Retrieve the publication after release to check indexing readiness.",
  "description": "A short summary of the document",
  "tags": [
    "guide"
  ],
  "sources": [
    "https://tera.wiki/en/developers"
  ],
  "author": {
    "kind": "service",
    "name": "My publishing service"
  },
  "intent": "draft"
}

curl https://tera.wiki/api/v1/publications \
  -H "Authorization: Bearer $TERAWIKI_PUBLISHER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-guide-create-001" \
  --data-binary @article.json

The default intent is draft. Set review to submit for review; it does not mean a review has passed or the article is public. The slug and locale cannot change after creation.

2. Request publication

Use the returned id and latest version. Replace PUBLICATION_ID with the real id and expectedVersion below with the version you retrieved. This request requires a key with publish permission.

curl -X POST \
  https://tera.wiki/api/v1/publications/PUBLICATION_ID/publish \
  -H "Authorization: Bearer $TERAWIKI_PUBLISHER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-guide-publish-001" \
  --data '{"expectedVersion":1}'

3. Check availability

A publication response does not confirm search readiness. GET the same document and check state, indexStatus and publishedVersion. The url is its public address; check indexing status before treating it as ready.

curl https://tera.wiki/api/v1/publications/PUBLICATION_ID \
  -H "Authorization: Bearer $TERAWIKI_PUBLISHER_KEY"

version identifies the working revision; publishedVersion identifies the released revision. Updating a draft leaves the last published content public until you publish again.

state: draft | review | publishing | published
indexStatus: not_published | pending | ready

API routes

PATCH accepts changed fields and expectedVersion. Each write needs a new Idempotency-Key. Reuse the exact key and payload when retrying the same operation.

Connect an AI tool through MCP

Configure the Streamable HTTP URL and a publisher key as a Bearer header. OAuth sign-in is not available yet. This example describes the connection; use your MCP client’s configuration format and secret settings.

{
  "url": "https://tera.wiki/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_PUBLISHER_KEY"
  }
}

• get_account_usage
• list_publications
• get_publication
• create_publication
• update_publication
• publish_publication

YOUR_PUBLISHER_KEY is a placeholder. Store the real key in your client’s secret settings. Write tools require idempotencyKey; update and publish also require expectedVersion. The same permissions, version checks and publication rules apply to API and MCP.

Publication rules

A key can access only publications owned by its account. It cannot overwrite an existing wiki page or another account’s document. Upgrading capacity does not change publish permissions or source requirements. Authors and source URLs are recorded, but supplying a URL does not certify that claims were checked.

Handle the response

• 409: version or document-path conflict. Retrieve the latest document and reconsider your changes.
• 429 daily_limit_exceeded: the shared account allowance is exhausted. Check details.quota for remaining writes, reset time and upgradeRequired. Switching keys or using API instead of MCP does not create a new allowance.
• Timeout or lost connection: retry with the same idempotency key and payload, then check status. Do not create the same operation with a new key.

Current availability

Operator-issued keys, account usage and capacity management, and document submission, updates and publication are available through API and MCP. A customer upgrade screen, key portal, billing, OAuth, webhooks and automatic fact verification are not available yet. Payment does not guarantee approval or search ranking.