API reference

2a.qa Public API · v1.0.0 · OpenAPI 3.1.0

The complete 2a.qa API reference. Everything on this page is generated from the same document served at openapi.json — it cannot drift from it.

Base URL

https://2a.qa/api/v1

Machine-readable document (OpenAPI 3.1)

/api/v1/openapi.json

Authentication

Every request carries a key in an Authorization header. There is no session, no cookie and no CSRF token on /api/v1 — the route you open in a signed-in browser is not the route your bot talks to.

Authorization: Bearer 2aq_live_…

Scopes

links:readlinks:writeanalytics:readassets:readassets:writelogs:readlogs:write

Issue a key from API key settings

Quickstart

curl -X POST https://2a.qa/api/v1/links \
  -H "Authorization: Bearer 2aq_live_***" \
  -H "Content-Type: application/json" \
  -d '{"originalUrl":"https://example.com/campaign",
       "customAlias":"sale"}'

# HTTP/2 201 Created
{"link":{"id":"clx…","shortCode":"sale","customAlias":"sale",
         "originalUrl":"https://example.com/campaign",
         "hasPassword":false,"trustPreview":false}}

The response does not carry a ready-made short URL — build it from the base URL and shortCode. That is deliberate: a custom domain can change it.

Links

Create, list and read analytics for short links.

GET/linkslinks:read

List links

Parameters

Name	In	Type	Required
`q`	query	string	—
`page`	query	integer	—
`pageSize`	query	integer · ≤100	—

Responses

200: Page of links
401: Missing, malformed, revoked or expired API key
403: Missing scope: links:read
503: The API-key feature is disabled on this deployment

Response shape (200)

`items`	Link[]
`total`	integer
`page`	integer
`pageSize`	integer

POST/linkslinks:write

Create a link

Request body

Name	Type	Required
`originalUrl`	string · uri	yes
`customAlias`	string · ≤32	—
`title`	string · ≤120	—
`description`	string · ≤500	—
`password`	string · ≤60	—
`expiresAt`	string · date-time	—
`trustPreview`	boolean	—

Responses

201: Created. The body carries `trustPreview` and `hasPassword`, which the list route does not return
400: Invalid JSON, zod validation error (object body), or an invalid/reserved custom alias
401: Missing, malformed, revoked or expired API key
403: Missing scope: links:write
409: Alias taken (including a retired code held as a tombstone), or a short-code race — retry
422: URL flagged unsafe by Safe Browsing. This body carries a `threats` array ALONGSIDE `error` — the only v1 error that adds a key
429: Link-creation rate limit exceeded
500: Link could not be created
503: The API-key feature is disabled on this deployment

Response shape (201)

link CreatedLink

GET/links/{id}/analyticsanalytics:read

Analytics for one link

Clicks bucketed by day, plus top countries, devices, browsers and referrers, conversions, and the 25 most recent clicks (display fields only — raw IP and user-agent are never returned). Requires `analytics:read`, which `links:read` does NOT imply: a bot that shortens links has no need for every visitor's country.

Parameters

Name	In	Type	Required
`id`	path	string	yes
`range`	query	7d \| 30d \| 90d	—

Responses

200: Aggregated analytics
400: Unknown range
403: Missing scope: analytics:read
404: No such link on this account
503: The API-key feature is disabled on this deployment

Files

List, inspect, rename and delete. The upload itself is on /api/files, not v1.

GET/filesfiles:read

List shared files (never the password hash — only hasPassword)

Responses

200: OK
403: Missing scope: files:read, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

GET/files/{id}files:read

One shared file

Responses

200: OK
403: Missing scope: files:read, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

PATCH/files/{id}files:write

Rename or re-schedule a file. password/slug/mimeType are refused by name

Responses

200: OK
403: Missing scope: files:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

DELETE/files/{id}files:write

Delete a file — archived to the black box FIRST, then removed

Responses

200: OK
403: Missing scope: files:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

Bio page

The page and its links — http/https only, Safe Browsing checked.

GET/biobio:read

The bio page and its links

Responses

200: OK
403: Missing scope: bio:read, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

PATCH/biobio:write

Edit displayName, bio, isPublished, filesEnabled. Appearance and slug are dashboard-only and refused by name

Responses

200: OK
403: Missing scope: bio:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

GET/bio/linksbio:read

List bio links

Responses

200: OK
403: Missing scope: bio:read, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

POST/bio/linksbio:write

Add a bio link (http/https only, Safe Browsing checked, max 30)

Responses

200: OK
403: Missing scope: bio:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

PATCH/bio/links/{id}bio:write

Edit one bio link — Safe Browsing re-runs only when the URL changes

Responses

200: OK
403: Missing scope: bio:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

DELETE/bio/links/{id}bio:write

Remove one bio link

Responses

200: OK
403: Missing scope: bio:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

Webhooks

Subscriptions and delivery log. The signing secret appears in the create response only.

GET/webhookswebhooks:read

List webhooks. The HMAC secret is NEVER in a list response

Responses

200: OK
403: Missing scope: webhooks:read, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

POST/webhookswebhooks:write

Create a webhook — the 201 body is the ONLY place the secret is ever shown

Responses

200: OK
403: Missing scope: webhooks:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

PATCH/webhooks/{id}webhooks:write

Toggle, re-subscribe or re-describe. url is not editable — delete and recreate

Responses

200: OK
403: Missing scope: webhooks:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

DELETE/webhooks/{id}webhooks:write

Delete a webhook

Responses

200: OK
403: Missing scope: webhooks:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

GET/webhooks/{id}/deliverieswebhooks:read

Delivery history for one webhook, newest first (?limit=1..100)

Responses

200: OK
403: Missing scope: webhooks:read, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

Domains

Custom domains and their verification.

GET/domainsdomains:read

List custom domains and the CNAME target

Responses

200: OK
403: Missing scope: domains:read, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

POST/domainsdomains:write

Responses

200: OK
403: Missing scope: domains:write, or the account is not entitled to this section
404: Not this account's, or not there
409: Hostname already registered — deliberately without saying by whom
503: Switched off on this deployment

POST/domains/{id}/verifydomains:write

Re-run DNS verification. 200 with ok:false means the check RAN and the records are not right yet

Responses

200: OK
403: Missing scope: domains:write, or the account is not entitled to this section
404: Not this account's, or not there
429: 30 verifications per hour per account
503: Switched off on this deployment

DELETE/domains/{id}/verifydomains:write

Remove a custom domain

Responses

200: OK
403: Missing scope: domains:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

Profile

Name and handle only — email, password and role are refused by name.

GET/profileprofile:read

The account profile

Responses

200: OK
403: Missing scope: profile:read, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

PATCH/profileprofile:write

Edit name and handle ONLY. email, password, role and isActive are refused by name — an API key must never be an account takeover

Responses

200: OK
403: Missing scope: profile:write, or the account is not entitled to this section
404: Not this account's, or not there
503: Switched off on this deployment

Assets (Majra)

Upload, list and delete bytes, plus upload tickets for untrusted clients.

GET/assetsassets:read

List assets

Parameters

Name	In	Type	Required
`q`	query	string	—
`kind`	query	IMAGE \| VIDEO \| AUDIO	—
`path`	query	string	—
`source`	query	string	—
`from`	query	string · date-time	—
`to`	query	string · date-time	—
`page`	query	integer	—
`pageSize`	query	integer · ≤100	—

Responses

200: Page of assets, newest first. List items carry MORE fields than GET /assets/{id} does — originalUrl, width, height, durationMs and source are here and not there
400: `from` or `to` is not a parseable RFC 3339 timestamp
401: Missing, malformed, revoked or expired API key
403: Missing scope: assets:read, or this account is not enrolled in Majra
503: Majra is not enabled on this deployment

Response shape (200)

`items`	AssetListItem[]
`total`	integer
`page`	integer
`pageSize`	integer

POST/assetsassets:write

Upload an asset

Responses

200: Deduplicated — identical bytes were already stored for this account, and the existing asset is returned
201: Created
400: Not multipart/form-data, missing `file`, empty upload, invalid `metadata`, or `retentionExempt` sent together with `expiresInDays`
401: Missing, malformed, revoked or expired API key
403: Missing scope: assets:write, or this account is not enrolled in Majra
409: Upload could not be committed under write contention — retry
413: Asset exceeds the per-asset size limit, or the account storage quota is reached
415: Unsupported media type. Allowed: png, jpeg, gif, webp, avif, mp4, webm, mp3, ogg, wav
429: Too many uploads (300/hour per key and IP), or the platform-wide storage ceiling is reached
500: Bytes could not be stored
503: Majra is not enabled on this deployment

Response shape (200)

`asset`	IngestedAsset
`deduped`	boolean

POST/assets/base64assets:write

Upload an asset as base64

Request body

Name	Type	Required
`base64`	string	yes
`filename`	string · ≤200	—
`path`	string · ≤163	—
`metadata`	object	—
`retentionExempt`	boolean	—
`expiresInDays`	integer	—
`source`	string · ≤60	—

Responses

200: Deduplicated — identical bytes were already stored for this account, and the existing asset is returned
201: Created
400: Body is not a JSON object, `base64` missing or not a string, not valid base64, decodes to nothing, invalid `metadata`, or `retentionExempt` sent together with `expiresInDays`
401: Missing, malformed, revoked or expired API key
403: Missing scope: assets:write, or this account is not enrolled in Majra
409: Upload could not be committed under write contention — retry
413: Decoded asset exceeds the per-asset size limit, or the account storage quota is reached
415: Unsupported media type. Allowed: png, jpeg, gif, webp, avif, mp4, webm, mp3, ogg, wav
429: Too many uploads (300/hour per key and IP), or the platform-wide storage ceiling is reached
500: Bytes could not be stored
503: Majra is not enabled on this deployment

Response shape (200)

`asset`	IngestedAsset
`deduped`	boolean

POST/assets/ticketsassets:write

Mint a single-use upload ticket

Pre-commits every constraint here, by the authenticated caller. The redeeming client cannot widen them and cannot set them at all — its `path`, `metadata` and `retentionExempt` are IGNORED, not merged. `token` is returned once; only its sha256 is stored.

Request body

Name	Type	Required
`maxBytes`	integer	—
`allowedKinds`	IMAGE \| VIDEO \| AUDIO[]	—
`path`	string · ≤163	—
`metadata`	object	—
`retentionExempt`	boolean	—
`ttlSec`	integer · ≤3600	—

Responses

201: Minted
400: Unknown `allowedKinds` value, or invalid `metadata`
401: Missing, malformed, revoked or expired API key
403: Missing scope: assets:write, or this account is not enrolled in Majra
429: Too many tickets (600/hour per key and IP)
503: Majra is not enabled on this deployment

Response shape (201)

ticket UploadTicket

POST/assets/tickets/{token}no key

Redeem an upload ticket (no API key)

multipart/form-data, field `file`. Any `path`, `metadata` or `retentionExempt` in the body is IGNORED — the ticket's pre-committed values win. The ticket is claimed BEFORE the bytes are read and is never returned to the pool: a failed upload needs a NEW ticket.

Parameters

Name	In	Type	Required
`token`	path	string	yes

Responses

200: Deduplicated — identical bytes were already stored for the minting account
201: Created
400: Not multipart/form-data, or missing `file`
403: The MINTING account is no longer enrolled in Majra
409: Upload could not be committed under write contention — mint a new ticket and retry
410: Malformed, already used, or expired token — one answer for all three, so a grinder cannot learn which guesses had the right shape
413: Asset exceeds the ticket's `maxBytes` or the platform ceiling, or the minting account's storage quota is reached
415: Unsupported media type, or a kind outside the ticket's `allowedKinds`
429: Too many redemptions (30/minute per IP; fails CLOSED when the limiter is unreachable)
500: Bytes could not be stored
503: Majra is not enabled on this deployment

Response shape (200)

`asset`	IngestedAsset
`deduped`	boolean

GET/assets/{id}assets:read

Get one asset

Parameters

Name	In	Type	Required
`id`	path	string	yes

Responses

200: The asset. Note it does NOT carry originalUrl, width, height, durationMs or source — the list route does
401: Missing, malformed, revoked or expired API key
403: Missing scope: assets:read, or this account is not enrolled in Majra
404: No such asset, or it belongs to another account — the two are deliberately indistinguishable
503: Majra is not enabled on this deployment

Response shape (200)

asset AssetDetail

PATCH/assets/{id}assets:write

Update an asset's display fields

Parameters

Name	In	Type	Required
`id`	path	string	yes

Request body

Name	Type	Required
`filename`	string · ≤200	—
`path`	string · ≤163	—
`retentionExempt`	boolean	—
`expiresInDays`	integer · nullable	—

Responses

200: Updated. Only the editable fields are echoed back
400: Body is not a JSON object, no editable field was sent (filename, path, retentionExempt, expiresInDays), or the result would be both `retentionExempt` and expiring
401: Missing, malformed, revoked or expired API key
403: Missing scope: assets:write, or this account is not enrolled in Majra
404: No such asset, or it belongs to another account
503: Majra is not enabled on this deployment

Response shape (200)

asset PatchedAsset

DELETE/assets/{id}assets:write

Delete an asset

Parameters

Name	In	Type	Required
`id`	path	string	yes

Responses

200: Deleted. `bytesReclaimed` is false when another asset still references the same content hash
401: Missing, malformed, revoked or expired API key
403: Missing scope: assets:write, or this account is not enrolled in Majra
404: No such asset, or it belongs to another account
503: Majra is not enabled on this deployment

Response shape (200)

`deleted`	boolean
`id`	string
`bytesReclaimed`	boolean

Events & alerts (Majra)

Ingest and query events, alert rules, and datasets.

GET/logslogs:read

Query log events

Parameters

Name	In	Type	Required
`dataset`	query	string	—
`X-2aqa-Dataset`	header	string	—
`q`	query	string	—
`level`	query	string	—
`resource`	query	string	—
`traceId`	query	string	—
`metadata.<path>`	query	string	—
`from`	query	string · date-time	—
`to`	query	string · date-time	—
`before`	query	string	—
`order`	query	asc \| desc	—
`includeTotal`	query	true \| false \| 1 \| 0	—
`limit`	query	integer · ≤100	—

Responses

200: Page of events, newest first. `total` is null unless `includeTotal=true`
400: No dataset named (header or query), unknown `level`, `order` other than asc/desc, unparseable `from`/`to`, `from` after `to`, a window wider than 31 days, more than 5 `metadata.` filters, an empty `metadata.` path, a malformed `before` cursor, or a `source` param (not a column on events — use `resource`)
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:read, or this account is not enrolled in Majra
404: Unknown dataset, or it belongs to another account. A PAUSED dataset still reads normally
429: Query rate limit exceeded (120/minute)
503: Majra is not enabled on this deployment

Response shape (200)

`items`	LogEvent[]
`nextBefore`	string · nullable
`hasMore`	boolean
`total`	integer · nullable

POST/logslogs:write

Ingest log events

Parameters

Name	In	Type	Required
`X-2aqa-Dataset`	header	string	—
`dataset`	query	string	—

Responses

202: Batch accepted — partially, if some elements were rejected. A batch where EVERY element was rejected is still a 202, with `accepted: 0` and no dataset created: check `accepted`, never the status code. `datasetCreated` is true when the name auto-created a new stream, which is how a typo'd dataset name surfaces
400: No dataset named (header or query), a dataset name that breaks `^[a-z0-9][a-z0-9_-]{0,63}$`, an unreadable body, invalid JSON, a body that is not an ARRAY (a bare object is refused — wrap it as `[{ … }]`), or an EMPTY array. An all-rejected batch is NOT a 400 — it is a 202 with `accepted: 0`
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:write, this account is not enrolled in Majra, or the dataset is paused
413: Batch exceeds 500 events or a 1 MB body
429: Ingest rate limit exceeded (600/minute, metered per API key — not per IP)
500: The dataset could not be opened, or the events could not be stored. Nothing was written
503: Log ingest is not enabled on this deployment

Response shape (202)

`status`	string
`accepted`	integer
`rejected`	integer
`datasetCreated`	boolean
`errors`	object[]

GET/logs/{id}logs:read

Get one log event

Parameters

Name	In	Type	Required
`id`	path	string	yes

Responses

200: The event. It carries THREE fields the list route omits — `dataset`, `apiKeyId` and the truncated `ip`
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:read, or this account is not enrolled in Majra
404: No such event, or it belongs to another account
503: Majra is not enabled on this deployment

Response shape (200)

event LogEventDetail

GET/alertslogs:read

List log-alert rules

Parameters

Name	In	Type	Required
`page`	query	integer	—
`pageSize`	query	integer · ≤100	—

Responses

200: Paged rules
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:read, or this account is not enrolled in Majra
503: Majra is not enabled on this deployment

Response shape (200)

`items`	AlertRule[]
`total`	integer
`page`	integer
`pageSize`	integer

POST/alertslogs:write

Create a log-alert rule

Fires the `log_alert` webhook when `threshold` matching events arrive within `windowSec`. Debounced: a rule that fires goes quiet for its whole window, so a crash loop emitting ten thousand errors sends one notification. At least one of `minLevel`, `messageContains` or `metadataMatch` is required — a rule with no predicate matches every event.

Request body

Name	Type	Required
`name`	string · ≤120	yes
`dataset`	string · nullable	—
`minLevel`	fatal \| error \| warn \| info \| debug \|	—
`messageContains`	string · nullable · ≤200	—
`metadataMatch`	object · nullable	—
`threshold`	integer · ≤100000	—
`windowSec`	integer · ≤86400	—
`isActive`	boolean	—

Responses

201: Created
400: Not a JSON object, unknown dataset, a value out of range, or no predicate at all
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:write, or this account is not enrolled in Majra
409: At most 50 alert rules per account
503: Majra is not enabled on this deployment

Response shape (201)

rule AlertRule

PATCH/alerts/{id}logs:write

Update a log-alert rule

Editing any predicate (`minLevel`, `messageContains`, `metadataMatch`) also CLEARS the debounce, so a rule changed to catch something urgent is not silent for the rest of its window.

Parameters

Name	In	Type	Required
`id`	path	string	yes

Request body

Name	Type	Required
`name`	string · ≤120	yes
`dataset`	string · nullable	—
`minLevel`	fatal \| error \| warn \| info \| debug \|	—
`messageContains`	string · nullable · ≤200	—
`metadataMatch`	object · nullable	—
`threshold`	integer · ≤100000	—
`windowSec`	integer · ≤86400	—
`isActive`	boolean	—

Responses

200: Updated
400: Not a JSON object, unknown dataset, a value out of range, or no editable field sent
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:write, or this account is not enrolled in Majra
404: No such rule, or it belongs to another account
503: Majra is not enabled on this deployment

Response shape (200)

rule AlertRule

DELETE/alerts/{id}logs:write

Delete a log-alert rule

Parameters

Name	In	Type	Required
`id`	path	string	yes

Responses

200: Deleted
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:write, or this account is not enrolled in Majra
404: No such rule, or it belongs to another account
503: Majra is not enabled on this deployment

Response shape (200)

`deleted`	boolean
`id`	string

GET/datasetslogs:read

List datasets

Parameters

Name	In	Type	Required
`page`	query	integer	—
`pageSize`	query	integer · ≤100	—

Responses

200: Page of datasets. `eventCount` is maintained by the ingest path and is approximate by design
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:read, or this account is not enrolled in Majra
429: Query rate limit exceeded (120/minute)
503: Majra is not enabled on this deployment

Response shape (200)

`items`	Dataset[]
`total`	integer
`page`	integer
`pageSize`	integer

POST/datasetslogs:write

Create a dataset

Request body

Name	Type	Required
`name`	string · ≤64	yes
`label`	string · nullable · ≤120	—
`description`	string · nullable · ≤2000	—
`retentionDays`	7 \| 30 \| 90 \| 180 \| 365	—
`hasPersonalData`	boolean	—

Responses

201: Created. `retentionDays` is echoed as STORED — a deployment ceiling below the tier you asked for snaps it down, and this body is where you see that
400: Invalid JSON, zod validation error (object body), a `name` that breaks the slug rule (the message names the offending character and its position), or a `retentionDays` outside the offered tiers
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:write, or this account is not enrolled in Majra
409: A dataset with that name already exists on this account
413: Body exceeds 16384 bytes
429: Ingest rate limit exceeded (600/minute)
500: Dataset could not be created
503: Majra is not enabled on this deployment

Response shape (201)

dataset Dataset

GET/datasets/{name}logs:read

Get one dataset

Parameters

Name	In	Type	Required
`name`	path	string	yes

Responses

200: The dataset
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:read, or this account is not enrolled in Majra
404: No such dataset, or it belongs to another account
429: Query rate limit exceeded (120/minute)
503: Majra is not enabled on this deployment

Response shape (200)

dataset Dataset

PATCH/datasets/{name}logs:write

Update a dataset

Parameters

Name	In	Type	Required
`name`	path	string	yes

Request body

Name	Type	Required
`label`	string · nullable · ≤120	—
`description`	string · nullable · ≤2000	—
`retentionDays`	7 \| 30 \| 90 \| 180 \| 365	—
`isActive`	boolean	—
`hasPersonalData`	boolean	—

Responses

200: Updated. `isActive: false` pauses ingestion; existing events stay readable
400: Invalid JSON, zod validation error (object body), a `retentionDays` outside the offered tiers, no editable field sent, or a `name` key — renaming is refused, not ignored
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:write, or this account is not enrolled in Majra
404: No such dataset, or it belongs to another account
413: Body exceeds 16384 bytes
429: Ingest rate limit exceeded (600/minute)
500: Dataset could not be updated
503: Majra is not enabled on this deployment

Response shape (200)

dataset Dataset

DELETE/datasets/{name}logs:write

Delete a dataset and its events

Destroys the dataset AND every event in it (FK cascade). No soft delete, no recycle bin. `confirmEvents` must equal the server's REAL count of events about to be destroyed — the 400 hands you that number. To stop a runaway emitter without losing data, PATCH `isActive: false` instead.

Parameters

Name	In	Type	Required
`name`	path	string	yes
`confirmEvents`	query	integer	yes

Responses

200: Deleted, together with every event it held
400: `confirmEvents` missing or not a non-negative integer. The message carries the real count to repeat back
401: Missing, malformed, revoked or expired API key
403: Missing scope: logs:write, or this account is not enrolled in Majra
404: No such dataset, or it belongs to another account (also returned if another request deleted it first)
409: `confirmEvents` does not match the live count — your picture of the dataset is stale. The message names the real number
429: Ingest rate limit exceeded (600/minute)
500: Dataset could not be deleted
503: Majra is not enabled on this deployment

Response shape (200)

`deleted`	boolean
`name`	string
`eventsDeleted`	integer

Public delivery

Byte-reading URLs. No key — these are what you put in a page or a message.

GET/a/{file}no key

Serve an asset (public)

served from https://2a.qa

Parameters

Name	In	Type	Required
`file`	path	string	yes

Responses

200: The bytes, inline. Cache-Control: public, max-age=31536000, immutable · CDN-Cache-Control: public, max-age=3600 · ETag is the content sha256 · Access-Control-Allow-Origin: * · Cross-Origin-Resource-Policy: cross-origin · X-Content-Type-Options: nosniff. `immutable` is honest ONLY on this shape: the id addresses a row whose bytes are content-addressed, so a re-upload of different bytes is a different id. Range IS honoured — send `Range: bytes=a-b` for a 206
206: Partial content for a single `Range: bytes=a-b` or `bytes=-n`. Content-Range names the served window and Content-Length is what was actually sent
304: `If-None-Match` matched. The ETag is the content sha256, so a match is proof the bytes are unchanged rather than a heuristic
404: Unknown id, extension does not match the stored type, asset disabled, expired, scanned infected, or the bytes are missing from disk — one response for all of them, and the body is the plain text `Not found`, NOT a JSON error object
416: Multi-range, malformed range, or a window past the end of the file. `Content-Range: bytes */<size>` names the real length so the client can re-ask

GET/a/u/{handle}/{path}no key

Serve an asset by its readable path (public)

`/a/u/<handle>/<folder>/<filename>` on the app origin, `/<handle>/<folder>/<filename>` on the dedicated asset origin. The LAST segment is the filename and the rest is the virtual folder; zero folder segments addresses an asset stored at the account root. Handle matching is case-insensitive; folder and filename are matched exactly against the stored columns. Where two assets share one (path, filename) the NEWEST wins. NOT a canonical address — a rename, a move, a handle change or a re-upload of the same name repoints it, which is why it is cached for minutes and carries `Link: <…>; rel="canonical"` naming the `/a/{file}` URL that is safe to store and share.

served from https://2a.qa

Parameters

Name	In	Type	Required
`handle`	path	string	yes
`path`	path	string	yes

Responses

200: The bytes, inline. Cache-Control: public, max-age=300 · CDN-Cache-Control: public, max-age=60 · Link: <canonical>; rel="canonical" · same ETag, CORS, CORP and nosniff headers as /a/{file}. NOT `immutable` — this URL is a lookup, not a content address
206: Partial content — same Range handling as /a/{file}
304: `If-None-Match` matched
404: Malformed handle, unknown handle, no asset with that folder+filename, too many or too long segments, disabled, expired, scanned infected, over quota with serving switched off, or the bytes are missing from disk — one indistinguishable `Not found` for all of them, so this URL space cannot be probed for which handles or filenames exist
416: Unsatisfiable range — same as /a/{file}

Spec & tickets

The machine-readable document itself, and management of outstanding upload tickets.

GET/ticketsassets:read

List the upload tickets this account has minted

Scoped to the ACCOUNT, not to the calling key: a ticket minted by a key that has since been revoked is precisely the one an operator needs to find. The token and its hash are NEVER returned — the token exists exactly once, in the mint response. If it was lost, mint another and revoke this one.

Parameters

Name	In	Type	Required
`page`	query	integer	—
`pageSize`	query	integer · ≤100	—

Responses

200: Page of tickets, newest first
401: Missing, malformed, revoked or expired API key
403: Missing scope: assets:read, or this account is not enrolled in Majra
503: Switched off on this deployment

Response shape (200)

`items`	UploadTicketRow[]
`total`	integer
`page`	integer
`pageSize`	integer

DELETE/tickets/{id}assets:write

Revoke an outstanding upload ticket

A hard delete, not a flag: a REVOKED ticket has produced nothing, so there is no `assetId` audit link to preserve, and the record that it was issued and withdrawn lives in the hash-chained activity log. An ALREADY-REDEEMED ticket is refused (409) rather than deleted, because its `assetId` is the trail from a leaked upload link to what it produced.

Parameters

Name	In	Type	Required
`id`	path	string	yes

Responses

200: Revoked
401: Missing, malformed, revoked or expired API key
403: Missing scope: assets:write, or this account is not enrolled in Majra
404: No such ticket for this account — a 404 and not a 403, so the id space cannot be probed for other accounts' tickets
409: Already redeemed, so it is already inert and is kept until its retention window closes. The body carries the `assetId` it produced
503: Switched off on this deployment

Response shape (200)

`revoked`	boolean
`id`	string

GET/openapi.jsonno key

This document

Responses

200: The OpenAPI 3.1 description of this API. Cache-Control: public, max-age=300, s-maxage=300

Schemas

The named shapes the tables above refer to.

Link

`id`	string
`shortCode`	string
`customAlias`	string · nullable
`originalUrl`	string · uri
`title`	string · nullable
`description`	string · nullable
`clickCount`	integer
`isActive`	boolean
`expiresAt`	string · date-time · nullable
`healthScore`	integer · ≤100
`healthStatus`	UNKNOWN \| HEALTHY \| WARNING \| BROKEN \| UNSAFE
`createdAt`	string · date-time

CreateLinkBody

`originalUrl`	string · uri
`customAlias`	string · ≤32
`title`	string · ≤120
`description`	string · ≤500
`password`	string · ≤60
`expiresAt`	string · date-time
`trustPreview`	boolean

CreatedLink

`id`	string
`shortCode`	string
`customAlias`	string · nullable
`originalUrl`	string · uri
`title`	string · nullable
`description`	string · nullable
`clickCount`	integer
`isActive`	boolean
`expiresAt`	string · date-time · nullable
`healthScore`	integer · ≤100
`healthStatus`	UNKNOWN \| HEALTHY \| WARNING \| BROKEN \| UNSAFE
`createdAt`	string · date-time
`trustPreview`	boolean
`hasPassword`	boolean

IngestedAsset

`id`	string
`url`	string · uri
`originalUrl`	string · uri
`kind`	IMAGE \| VIDEO \| AUDIO
`mimeType`	image/png \| image/jpeg \| image/gif \| image/webp \| image/avif \| video/mp4 \| video/webm \| audio/mpeg \| audio/ogg \| audio/wav
`size`	integer
`width`	integer · nullable
`height`	integer · nullable
`durationMs`	integer · nullable
`path`	string · nullable
`filename`	string · nullable
`metadata`	object · nullable
`retentionExempt`	boolean
`expiresAt`	string · date-time · nullable
`createdAt`	string · date-time

AssetListItem

`id`	string
`url`	string · uri
`originalUrl`	string · uri
`kind`	IMAGE \| VIDEO \| AUDIO
`mimeType`	string
`size`	integer
`width`	integer · nullable
`height`	integer · nullable
`durationMs`	integer · nullable
`path`	string · nullable
`filename`	string · nullable
`metadata`	object · nullable
`source`	string · nullable
`requests`	integer
`bytesServed`	integer
`isActive`	boolean
`virusScanStatus`	pending \| clean \| infected \| skipped \| error
`retentionExempt`	boolean
`expiresAt`	string · date-time · nullable
`createdAt`	string · date-time

AssetDetail

`id`	string
`url`	string · uri
`kind`	IMAGE \| VIDEO \| AUDIO
`mimeType`	string
`size`	integer
`filename`	string · nullable
`path`	string · nullable
`metadata`	object · nullable
`requests`	integer
`bytesServed`	integer
`isActive`	boolean
`virusScanStatus`	pending \| clean \| infected \| skipped \| error
`retentionExempt`	boolean
`expiresAt`	string · date-time · nullable
`createdAt`	string · date-time

PatchedAsset

`id`	string
`filename`	string · nullable
`path`	string · nullable
`retentionExempt`	boolean
`expiresAt`	string · date-time · nullable

UploadAssetForm

`file`	string · binary
`filename`	string · ≤200
`path`	string · ≤163
`metadata`	string
`retentionExempt`	true \| false
`expiresInDays`	string
`source`	string · ≤60

Base64UploadBody

`base64`	string
`filename`	string · ≤200
`path`	string · ≤163
`metadata`	object
`retentionExempt`	boolean
`expiresInDays`	integer
`source`	string · ≤60

PatchAssetBody

`filename`	string · ≤200
`path`	string · ≤163
`retentionExempt`	boolean
`expiresInDays`	integer · nullable

LogEvent

`id`	string
`level`	fatal \| error \| warn \| info \| debug
`message`	string
`resource`	string · nullable
`traceId`	string · nullable
`metadata`	object · nullable
`timestamp`	string · date-time
`receivedAt`	string · date-time

LogEventDetail

`id`	string
`dataset`	string
`level`	fatal \| error \| warn \| info \| debug
`message`	string
`resource`	string · nullable
`traceId`	string · nullable
`metadata`	object · nullable
`apiKeyId`	string
`ip`	string · nullable
`timestamp`	string · date-time
`receivedAt`	string · date-time

LogEventInput

`level`	fatal \| error \| warn \| info \| debug
`message`	string · ≤8192
`resource`	string · ≤128
`traceId`	string · ≤128
`timestamp`	string · date-time
`metadata`	object

UploadTicket

`uploadUrl`	string · uri
`token`	string
`maxBytes`	integer
`allowedKinds`	IMAGE \| VIDEO \| AUDIO[]
`expiresAt`	string · date-time

MintTicketBody

`maxBytes`	integer
`allowedKinds`	IMAGE \| VIDEO \| AUDIO[]
`path`	string · ≤163
`metadata`	object
`retentionExempt`	boolean
`ttlSec`	integer · ≤3600

AlertRule

`id`	string
`name`	string
`dataset`	string · nullable
`minLevel`	fatal \| error \| warn \| info \| debug \|
`messageContains`	string · nullable
`metadataMatch`	object · nullable
`threshold`	integer
`windowSec`	integer
`isActive`	boolean
`lastFiredAt`	string · date-time · nullable
`createdAt`	string · date-time

CreateAlertBody

`name`	string · ≤120
`dataset`	string · nullable
`minLevel`	fatal \| error \| warn \| info \| debug \|
`messageContains`	string · nullable · ≤200
`metadataMatch`	object · nullable
`threshold`	integer · ≤100000
`windowSec`	integer · ≤86400
`isActive`	boolean

Dataset

`id`	string
`name`	string · ≤64
`label`	string · nullable
`description`	string · nullable
`retentionDays`	integer
`isActive`	boolean
`hasPersonalData`	boolean
`eventCount`	integer
`lastEventAt`	string · date-time · nullable
`createdAt`	string · date-time

CreateDatasetBody

`name`	string · ≤64
`label`	string · nullable · ≤120
`description`	string · nullable · ≤2000
`retentionDays`	7 \| 30 \| 90 \| 180 \| 365
`hasPersonalData`	boolean

UpdateDatasetBody

`label`	string · nullable · ≤120
`description`	string · nullable · ≤2000
`retentionDays`	7 \| 30 \| 90 \| 180 \| 365
`isActive`	boolean
`hasPersonalData`	boolean

UploadTicketRow

One minted upload credential AS LISTED. `token` and `tokenHash` are absent by design — the verifier the redeem route compares against and is never serialised — publishing it through a read scope would make it a bearer credential in its own right.

`id`	string
`maxBytes`	integer
`allowedKinds`	string[]
`path`	string · nullable
`expiresAt`	string · date-time
`usedAt`	string · date-time · nullable
`assetId`	string · nullable
`createdAt`	string · date-time

Error

error string | object

2a.qa openapi.json