Posts endpoints

Read-side endpoints for the posts the caller owns. All three accept either API-key or session auth.

GET /api/v1/posts

List the authenticated user's posts.

Auth

API key or session auth.

Query parameters

Name	Type	Required	Description
page	number	No	Defaults to 1
limit	number	No	Defaults to 20, max 100
tag	string	No	Lowercase tag filter — only posts with this tag
workspaceId	string	No	Scope the list to one workspace. The CLI sends this by default for the active workspace; omit it to list authored posts across all workspaces.
projectId	string	No	Scope slug/list results to one project. The CLI sends this by default for the active project.

Example

curl "https://api.opendocs.cc/api/v1/posts?page=1&limit=20&tag=api" \
  -H "Authorization: Bearer od_live_xxxxx"

Response

{
  "posts": [
    {
      "id": "post_123",
      "slug": "checkout-api-reference",
      "title": "Checkout API reference",
      "summary": "Endpoint summary.",
      "visibility": "workspace",
      "isPublished": true,
      "updatedAt": "2026-04-12T10:00:00.000Z",
      "workspaceId": "ws_123",
      "workspaceSlug": "acme",
      "projectId": "proj_default",
      "projectSlug": "default",
      "projectName": "Default",
      "isDefaultProject": true,
      "tags": ["api", "checkout"]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

visibility can be private, workspace, or public.

GET /api/v1/posts/:postId

Return metadata for a single post.

:postId can be either the post UUID or the post slug. Slug lookups can be scoped with ?workspaceId=ws_123&projectId=proj_123, which is how the CLI disambiguates the same slug used in multiple workspaces or projects. UUID lookups ignore those query parameters because UUIDs are globally unique.

Response

{
  "post": {
    "id": "post_123",
    "slug": "checkout-api-reference",
    "title": "Checkout API reference",
    "summary": "Endpoint summary.",
    "visibility": "workspace",
    "isPublished": true,
    "publishedAt": "2026-04-12T10:00:00.000Z",
    "updatedAt": "2026-04-12T10:00:00.000Z",
    "url": "/acme/checkout-api-reference",
    "projectId": "proj_default",
    "projectSlug": "default",
    "projectName": "Default",
    "isDefaultProject": true,
    "versionNumber": 1,
    "tags": ["api", "checkout"]
  }
}

Default project URLs are /<workspace-slug>/<post-slug>. Non-default project URLs are /<workspace-slug>/projects/<project-slug>/<post-slug>. Prepend https://opendocs.cc to get the absolute URL.

GET /api/v1/posts/:postId/raw

Return the current raw Markdown for a post.

Like GET /posts/:postId, this accepts either a UUID or slug and supports the optional ?workspaceId= query parameter for slug disambiguation.

Response

{
  "markdown": "# Checkout API reference\n\nEndpoint summary.",
  "title": "Checkout API reference",
  "slug": "checkout-api-reference",
  "versionNumber": 1
}

Used by the CLI's opendocs pull <postId> to reconstitute the local file.

Common errors

Status	error	When
401	unauthorized	Missing/invalid API key
404	not_found	Post doesn't exist, belongs to a workspace the caller isn't a member of, or the slug exists in a different workspace than workspaceId
429	rate_limited	120/min general bucket exhausted

Related pages

• Post mutation endpoints — update, unpublish, visibility, tags
• Export endpoints — single and batch export to PDF / DOCX / Markdown
• Errors and pagination — full error catalogue