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 while keeping earlier versions available.

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.

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 "https://apirecap.com/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.

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 creates an immutable version and makes it the latest.

Run after a successful deploymentPOST
curl -fS -X POST "https://apirecap.com/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 that version, while previous versions keep their own URLs. APIRecap can compare adjacent versions so readers can see what changed. If your workflow sends a JSON body instead of a file, PUT /api/v1/projects/{project}/apis/{api-slug} also publishes the next version.

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 input returns a validation error without publishing a version. Missing or revoked keys return 401; a key without edit access returns 403.

05 / READERS

Sharing and team access

Publishing updates the stored documentation; the project Owner controls whether external readers can see it. Turn on project sharing and choose listed or unlisted access to give clients a link. Private APIs remain available only to authorised signed-in team members.

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