REST API v1

Authentication

Create an API key on the API keys page in the dashboard. Bidama shows the full key once, right after you create it, and only stores a hash, so copy it somewhere safe. Send the key as a bearer token on every request. The only route that works without a key is the OpenAPI download.

Authorization: Bearer bdma_<key>

Each key carries one or more scopes. Scopes don't include each other, so a key with only write can't call GET routes. Give a key every scope it needs.

If authentication fails you get one of these codes:

• invalid_api_key (401): the key is missing, malformed, unknown, or revoked.
• user_disabled (403): the account that owns the key has been disabled.
• insufficient_scope (403): the key is valid but doesn't have the scope this route needs.

Quickstart

Check that your key works, then create a short link:

curl -sS \
  -H "Authorization: Bearer $BIDAMA_API_KEY" \
  https://<your-host>/api/v1/me

curl -sS \
  -H "Authorization: Bearer $BIDAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"link","target_url":"https://example.com","title":"Example"}' \
  https://<your-host>/api/v1/resources

The response is the new resource, including its slug and public url.

How the API behaves

• Your data only. Every route works on resources you own. A slug that doesn't exist, or a resource you deleted, returns 404 not_found. A resource that belongs to another account returns 403 forbidden on the resource routes and 404 elsewhere. Your own expired resources stay readable and editable through the API.
• Errors. Failures return JSON with a readable error message and a stable error_code. Validation errors usually name the field as well. Match on error_code, not the message.
• Rate limits. Every request counts against a budget for your IP address, and requests with a valid key also count against a budget for that key. Both default to 100 requests a minute, so several keys used from one machine share the IP budget. Creating links through POST /api/v1/resources has an extra limit of 60 an hour by default. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Going over returns 429 rate_limited with a Retry-After header.
• Body size. Plain JSON requests can be up to 1 MiB. Uploads follow the server's upload limit (50 MiB unless the operator changed it), and HTML artifacts have their own limits (see below).
• Safe edits. Reads and writes of a single resource return an X-Resource-ETag header. Send that value back unchanged as X-Resource-If-Match when you update the resource. If someone changed it in the meantime you get 412 etag_mismatch instead of silently overwriting their edit. Collection item routes use X-Collection-ETag and X-Collection-If-Match in the same way. The standard If-Match header still works, but new clients should use the X- headers, because proxies can rewrite a normal ETag.
• Pagination. GET /resources and GET /jobs return next_cursor when there are more results; pass it back as ?cursor=. The submission lists take limit and offset and return a total. Upload requests and webhooks come back as a single list.
• Analytics. Your own API calls never count as views of your resources.

Endpoints

This is every route under /api/v1, with the scope it needs. The OpenAPI document has the same routes with full request and response schemas, which is handy for generating a client.

Account

AI agents can use the same features through the MCP server, which signs in with OAuth instead of API keys.

Resources

HTML artifacts

Collections

Bio pages

Markdown versions

Notion and background jobs

Routes that queue work answer 202 Accepted with a job_id, a poll_url, and retry_after_seconds. Poll the job until it finishes. If the same work is already queued you get 409 job_already_active.

Upload requests

An upload request is a private link that lets other people send you files without an account.

Analytics

The summary covers all time unless you pass days (1 to 365) or both from and to as YYYY-MM-DD. Exports cover the last 30 days unless you pass from and to. An export stops at 100,000 rows, and its X-Bidama-Truncated header tells you whether it did.

Webhooks

You can subscribe to resource.created, resource.updated, resource.deleted, resource.expired, link.clicked, upload_request.submitted, and upload_request.reviewed. Click events are sent only for links with webhook_clicks turned on. Each delivery is signed. Check X-Bidama-Webhook-Signature, which is v1= followed by the hex HMAC-SHA256 of timestamp + "." + body, using the timestamp from X-Bidama-Webhook-Timestamp.

Creating resources

POST /api/v1/resources takes a JSON body, and the type field decides which other fields apply:

Every type also accepts slug, title, description, visibility, password, starts_at, expires_at, and labels. A successful create returns 201 with the same body you would get from GET /api/v1/resources/{slug}.

• Slugs are 3 to 64 characters of lowercase letters, digits, hyphens, and underscores. Leave out slug and Bidama picks a random 8-character one.
• visibility is public (the default), unlisted, or private, and can't be changed later. Timestamps are RFC 3339, and starts_at must come before expires_at.
• You can add up to 20 labels of lowercase letters, digits, hyphens, and underscores.
• Files and images go through POST /api/v1/uploads as multipart/form-data, with the file in a part called file and the common fields alongside it (except starts_at). max_views works for files but not images. Add type=image or type=file if you want the upload rejected when the content turns out to be the other kind.
• Creating a Notion mirror also queues its first refresh. If that can't be queued, nothing is created.

HTML artifacts

An artifact is a static website: HTML, CSS, JavaScript, images, and so on. Its share link looks like any other, https://<host>/<slug>. After Bidama checks the password, expiry, and visibility, it sends the visitor to the site on its own isolated origin. Artifacts need to be turned on by the server operator; check features.artifacts_enabled in GET /api/v1/me.

Send multipart/form-data with a text part named metadata that holds a JSON object:

{
  "slug": "optional-slug",
  "title": "Optional title",
  "description": "Optional description",
  "visibility": "public",
  "password": "optional password",
  "expires_at": "2026-08-01T00:00:00Z",
  "labels": ["demo"]
}

Then add the site's files in one of two ways. You can't mix them.

• As a ZIP. Add one file part named archive.
• As separate files. List them in metadata.files as {"part": "f0", "path": "index.html"} entries, then add one file part per entry under the name you gave it in part. The path comes from metadata; the uploaded file name is ignored.

The entry page is index.html at the root of the site. If there isn't one, Bidama uses the first .html or .htm file. Either way the page can't be empty. Paths must be plain relative paths: no .., no backslashes, and no two paths that differ only in letter case.

Paths starting with .auth or _bidama are reserved. By default a site can be up to 100 MiB in total, with at most 500 files, no file over 50 MiB, and a ZIP of at most 50 MiB. Your server may set lower limits. max_views isn't supported for artifacts.

To publish a new version, post to /api/v1/resources/{slug}/artifact/deployments. You can send the whole site again the same way, or send a patch: set "mode": "patch" and the current base_deployment_id, upload only the files that changed, and list removed files in delete_paths. Each new version gets a new origin, and the share link always points to the latest one.

Errors

Every error has the same shape:

{
  "error": "Enter a valid URL.",
  "error_code": "validation_failed",
  "field": "target_url"
}

These are the codes you're most likely to see:

See also: MCP server · OpenAPI document