Help Center API Reference

Retrieve the draft and its changes

Returns the draft that waits for review, with the change report against the live revision: endpoints added, removed, changed (one line per change) and moved, whether a change is breaking, and whether the servers or security schemes changed.

GET

/v2/help_center/api_specs/{specId}/draft

curl --request GET \
  --url https://do.featurebase.app/v2/help_center/api_specs/{specId}/draft \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit'

{
  "baseRevision": 7,
  "breaking": false,
  "changes": {
    "added": [
      {
        "key": "GET /posts/{postId}",
        "stableKey": "GET /posts/{}"
      }
    ],
    "changed": [
      {
        "breaking": true,
        "key": "GET /posts/{postId}",
        "lines": [
          "<string>"
        ],
        "stableKey": "GET /posts/{}"
      }
    ],
    "counts": {
      "added": 123,
      "breaking": 123,
      "changed": 123,
      "removed": 123,
      "unchanged": 123
    },
    "moved": [
      {
        "fromKey": "<string>",
        "fromStableKey": "<string>",
        "stableKey": "<string>",
        "toKey": "<string>"
      }
    ],
    "removed": [
      {
        "key": "GET /posts/{postId}",
        "stableKey": "GET /posts/{}"
      }
    ],
    "securitySchemesChanged": true,
    "serversChanged": true,
    "truncated": true
  },
  "createdAt": "2026-10-01T12:00:00.000Z",
  "error": "<string>",
  "liveRevision": 7,
  "object": "help_center_api_spec_draft",
  "operationCount": 44,
  "readyAt": "2026-10-01T12:00:00.000Z",
  "revision": 8,
  "skipped": [
    {
      "key": "<string>",
      "reason": "<string>"
    }
  ],
  "spec": {
    "openapi": "<string>",
    "servers": [
      {
        "url": "<string>"
      }
    ],
    "title": "<string>",
    "version": "<string>"
  },
  "specId": "66f7d0c1a2b3c4d5e6f70812",
  "status": "ready",
  "trigger": "ci",
  "warningCounts": {},
  "warnings": [
    {
      "code": "<string>",
      "message": "<string>",
      "operationKey": "<string>"
    }
  ]
}

Review it, then publish with draftRevision = revision and baseRevision = baseRevision, or discard it.

Lists are capped (changes.truncated); the counts stay exact. Only the first 100 warnings are listed (warningCounts has all).

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

specIdstringrequired

The API reference version (id from the list).

Example: 66f7d0c1a2b3c4d5e6f70812

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Response

Success

baseRevisionnumber | nullrequired

Send it as baseRevision to publish. Null for a first import.

Example: 7

breakingbooleanrequired

True when an endpoint was removed or changed in a breaking way.

Example: false

changesobject | nullrequired

The change report against baseRevision. Null while the draft builds.

Show child attributes

createdAtstring | nullrequired

When the draft was created.

Example: 2026-10-01T12:00:00.000Z

errorstring | nullrequired

liveRevisionnumber | nullrequired

The live revision now.

Example: 7

objectenum<string>required

Available options: help_center_api_spec_draft

Example: help_center_api_spec_draft

operationCountnumberrequired

Endpoints in the draft.

Example: 44

readyAtstring | nullrequired

When the draft was ready.

Example: 2026-10-01T12:00:00.000Z

revisionnumberrequired

Send it as draftRevision to publish or discard.

Example: 8

skippedobject[]required

Endpoints left out of the import, with the reason.

Show child attributes

specobjectrequired

Show child attributes

specIdstringrequired

Example: 66f7d0c1a2b3c4d5e6f70812

statusenum<string>required

ready can be published; building is still in progress; failed see error.

Available options: building, ready, failed, superseded, gc

Example: ready

triggerenum<string>required

What created the draft.

Available options: upload, url-manual, url-cron, ci, featurebase, renormalize

Example: ci

warningCountsobjectrequired

Warning count per code.

warningsobject[]required

Import warnings (the first 100).

Show child attributes

Still need help? Ask the team