Quickstart

The TPC API is in alpha development. If you’re interested in using it for a production use case, contact support@promptingco.com to discuss your requirements.

You can make your first content request in under five minutes if you already have access to a TPC organization.

Step 1: Create an API key

Open your organization API key settings:

https://app.promptingco.com/{orgSlug}/settings/api-keys

Create a key with these scopes:

content:read
content:write

Copy the key immediately. TPC shows the secret once.

Use a read-only key with only content:read until your integration needs to create, update, or delete content.

Step 2: Make your first request

Export your key and product ID:

export TPC_API_KEY="tpc_api_key_here"
export TPC_PRODUCT_ID="product_123"

List published content for the product:

curl "https://app.promptingco.com/api/v1/content?productId=$TPC_PRODUCT_ID&page=1&pageSize=10" \
  -H "x-api-key: $TPC_API_KEY"

A successful response returns ok: true. This example omits filter metadata and additional item fields:

{
  "ok": true,
  "data": {
    "scope": {
      "product": {
        "id": "product_123",
        "name": "Example Product",
        "slug": "example"
      },
      "organization": {
        "id": "org_123",
        "name": "Example Org",
        "slug": "example-org"
      }
    },
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "totalPages": 1,
    "items": [
      {
        "id": "page_123",
        "kind": "document",
        "title": "Pricing",
        "filePath": "pricing",
        "sourceUrl": "/pricing",
        "status": "published",
        "type": "manual",
        "isManual": true,
        "metaTitle": "Pricing",
        "metaDescription": null,
        "publishedAt": "2026-04-30T00:00:00.000Z",
        "createdAt": "2026-04-30T00:00:00.000Z",
        "updatedAt": "2026-04-30T00:00:00.000Z",
        "domains": []
      }
    ]
  }
}

Step 3: Parse the envelope

Every JSON endpoint returns an ApiResult<T>:

type ApiResult<T> =
  | { ok: true; data: T }
  | { ok: false; code: string; message: string; details?: unknown };

Handle both branches explicitly:

const response = await fetch(
  `https://app.promptingco.com/api/v1/content?productId=${productId}`,
  {
    headers: {
      "x-api-key": process.env.TPC_API_KEY!,
    },
  },
);

const result = await response.json();

if (!result.ok) {
  throw new Error(`${result.code}: ${result.message}`);
}

console.log(result.data.items);

Step 4: Add pagination and filters

The content list endpoint accepts query-string filters:

curl "https://app.promptingco.com/api/v1/content?productId=$TPC_PRODUCT_ID&query=pricing&status=published&page=1&pageSize=25&orderBy=updatedAt&orderByDirection=desc" \
  -H "x-api-key: $TPC_API_KEY"

Common filters:

Query parameter	Purpose
`query` or `q`	Search page title and content metadata.
`status`	`published` (default) or `draft` for live pages; `pending_review`, `generating`, `failed`, `rejected`, or `approved` for review-queue drafts.
`pathPrefix`	Return pages under a path, such as `blog/`.
`hasContent`	Return pages with or without stored content.
`page` and `pageSize`	Page through up to 100 items per request.

Step 5: Create a page

Create a page with content:write:

curl "https://app.promptingco.com/api/v1/content" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $TPC_API_KEY" \
  -H "Idempotency-Key: content-create-pricing-2026-04-30" \
  --data '{
    "productId": "'"$TPC_PRODUCT_ID"'",
    "pages": [
      {
        "slug": "docs/api-quickstart",
        "title": "API quickstart",
        "content": "# API quickstart\n\nCreated from the TPC API."
      }
    ]
  }'

Example response (organization and product scope omitted):

{
  "ok": true,
  "data": {
    "createdCount": 1,
    "failedCount": 0,
    "created": [
      {
        "id": "page_456",
        "slug": "docs/api-quickstart",
        "title": "API quickstart",
        "sourceUrl": null,
        "status": "pending_review"
      }
    ],
    "failed": []
  }
}

Check failedCount and failed even when ok is true: a batch can contain per-page failures. The id in each created item is a draft ID. Created pages land in the review queue. Approve and publish them with POST /api/v1/content/{draftId}/review ({"action": "approve"}) — approval queues publishing automatically — or browse the queue with GET /api/v1/content?productId=$TPC_PRODUCT_ID&status=pending_review.

Troubleshooting

Status	Error	What to check
`401`	`UNAUTHORIZED`	The key is missing, revoked, mistyped, or sent with the wrong header.
`403`	`insufficient_scope`	Add the missing scope or use a key created for this workflow.
`404`	`NOT_FOUND`	Confirm the product belongs to the organization that owns the key.
`409`	`CONFLICT`	You reused an `Idempotency-Key` with a different request body.
`429`	`RATE_LIMITED` or `TOO_MANY_REQUESTS`	Honor `Retry-After` when present; otherwise retry with backoff.

Every response includes x-request-id. Include that value when you contact support.

Get started

Concepts

Content API

API Reference

Quickstart

Quickstart

Step 1: Create an API key

Step 2: Make your first request

Step 3: Parse the envelope

Step 5: Create a page

Troubleshooting

​Quickstart

​Step 1: Create an API key

​Step 2: Make your first request

​Step 3: Parse the envelope

​Step 4: Add pagination and filters

​Step 5: Create a page

​Troubleshooting

Quickstart

Step 1: Create an API key

Step 2: Make your first request

Step 3: Parse the envelope

Step 4: Add pagination and filters

Step 5: Create a page

Troubleshooting