APIRecap
Join waitlist

PUBLISHING API / V1

Publish docs
with every release.

Create an API once, then send an updated document after each successful deployment. APIRecap makes the new version current and keeps earlier documents for your team. Owners and Editors can delete versions. The Owner controls external access to version history.

First publish? Start with the project and key setup below, then run the create request. Return here for the version-upload command after your next deployment.

Create an API Publish an update
01 / SET UP

Before you start

Create a project in APIRecap and note its numeric ID from the project URL, for example /projects/1. Then create a named publishing key in Settings → API keys. Copy it when shown: the full key cannot be retrieved later.

Use a bearer key. Keep it in your deployment's secret store and send it in the Authorization: Bearer header. Owners and Editors can publish to projects they can edit; Readers cannot publish.

In the commands below, replace project 1, the API slug payments, and the local file path with your values. Set APIRECAP_API_KEY in your shell or CI secret store. Set APIRECAP_URL to https://apirecap.com for the hosted service, or your own instance's base address without a trailing slash. A localhost address works only on your own machine.

02 / CREATE

Create an API from a document

Use POST /api/v1/projects/{project}/apis to create a new API inside an existing project. The request needs a name and a document. A slug is optional; if omitted, APIRecap suggests one from the name.

Create from an OpenAPI YAML filePOST
curl -fS -X POST "$APIRECAP_URL/api/v1/projects/1/apis" \
  -H "Authorization: Bearer $APIRECAP_API_KEY" \
  -F "name=Payments" \
  -F "slug=payments" \
  -F "document=@openapi.yaml"

A successful create returns 201 Created with the API ID, project ID, slug, format, visibility, and "version": 1. Use the slug for later updates. The example shows an Owner's key: new APIs default to listed for Owners and private for Editors.

Example response201
{"id":7,"project_id":1,"name":"Payments","slug":"payments","version":1,"format":"openapi_yaml","visibility":"listed"}

For a JSON request, send an OpenAPI object in document with Content-Type: application/json. For Markdown or YAML text in JSON, set format to markdown or openapi_yaml and pass the source text in document.

03 / UPDATE

Publish the next version

After a successful production deployment, send the replacement file to POST /api/v1/projects/{project}/apis/{api-slug}/versions. Each accepted request stores a new version and makes it the latest. Its content stays unchanged unless you delete that version.

Run after a successful deploymentPOST
curl -fS -X POST "$APIRECAP_URL/api/v1/projects/1/apis/payments/versions" \
  -H "Authorization: Bearer $APIRECAP_API_KEY" \
  -F "document=@openapi.yaml"

The response returns the new version number. Your current docs link points to it; retained versions keep their own URLs. External access to older versions depends on the Owner's sharing settings. Source comparisons show adjacent retained versions. Release facts compare the new document with the version that was current before publishing. If your workflow sends a JSON body instead of a file, PUT /api/v1/projects/{project}/apis/{api-slug} also publishes the next version.

For API publishes, APIRecap tries to draft a private release note from the detected changes. If a suggestion is unavailable, you can write the note yourself. An Owner or Editor checks and approves it before readers see the note. Subscribers receive a release alert after that first approval.

Example response200
{"id":7,"project_id":1,"name":"Payments","slug":"payments","version":2,"format":"openapi_yaml"}
Publish after deployment succeeds. Place the version upload command after your production release step so readers do not see unreleased documentation.
04 / INPUT

Formats and limits

OpenAPI JSON.json file or JSON object
OpenAPI YAML.yaml or .yml file, or YAML text
Markdown.md file or UTF-8 text

OpenAPI 3.0 and 3.1 documents are validated before storage. Documents have a 2 MB limit. The first document fixes that API's format: later versions must use the same type. To change from YAML to JSON or Markdown, create another API.

Invalid requests do not publish a version. Use the response to check what needs to change:

StatusWhat to do
401 · Invalid keyCheck the bearer key. Replace it if revoked, or if its account no longer has publishing access.
403 · Forbidden actionCheck the key owner's permissions. Only the workspace Owner can change external visibility.
404 · Not foundCheck the project ID and API slug. Projects outside the key's access are also unavailable.
413 · Request too largeReduce the JSON request to 2 MB or less. Oversized uploaded files can instead return 422.
415 · Unsupported requestSend a JSON body or a multipart file upload using the examples above.
422 · Validation failedRead the field errors. Check the document, file size, slug and API format before retrying.
05 / READERS

Sharing and team access

When project sharing is on, listed APIs appear on its share page and use the project link. Unlisted APIs stay off that page and need their own link. Private APIs have no external link; only authorised signed-in team members can read them. The Owner can turn sharing off to disable every external link for that project.

External readers can subscribe from a shared project or API page. They confirm their email before receiving alerts, which are sent when an Owner or Editor first approves a version's release note.

The Owner can invite Editors to publish and Readers to view selected projects. Team roles and permissions are explained on the team access page.

Join the waitlist