API reference

Aperture API reference

A typed, REST-shaped API. Base URL https://api.aperture.dev/v3. Authenticate every request with a bearer token. All responses are JSON.

v3.4OpenAPI 3.1 specWhat’s new

List projects

GET/v3/projects

Returns a cursor-paginated list of projects, most recent first. Use the query parameters to filter and page through results.

Query parameters for GET /v3/projects
Parameter	Type	Description
limit	integer	Page size, 1–100. Defaults to 20.
status	string	Filter by status: 'active', 'paused', or 'archived'.
cursor	string	A cursor from a prior response, to fetch the next page.

RequestcURL

GET /v3/projectsbash

curl https://api.aperture.dev/v3/projects?limit=10 \
  -H "Authorization: Bearer sk_live_•••"

Response200 OK

application/jsonjson

{
  "object": "list",
  "url": "/v3/projects",
  "has_more": true,
  "next_cursor": "crs_9aF2",
  "data": [
    {
      "id": "prj_8Kd2",
      "name": "Aperture",
      "status": "active",
      "created": 1717200000
    }
  ]
}

Create a project

POST/v3/projects

Creates a project. Pass an Idempotency-Key header to make the call safe to retry — repeating it returns the original project instead of creating a duplicate.

Body parameters for POST /v3/projects
Parameter	Type	Description
namerequired	string	A human-readable name, 1–80 characters.
regionrequired	string	Data region: 'us', 'eu', or 'ap'.
metadata	object	Up to 20 key/value pairs to attach to the project.

RequestcURL

POST /v3/projectsbash

curl -X POST https://api.aperture.dev/v3/projects \
  -H "Authorization: Bearer sk_live_•••" \
  -H "Idempotency-Key: a1b2c3" \
  -d '{ "name": "Aperture", "region": "eu" }'

Response201 Created

application/jsonjson

{
  "id": "prj_8Kd2",
  "object": "project",
  "name": "Aperture",
  "region": "eu",
  "status": "active"
}

Retrieve a project

GET/v3/projects/{id}

Fetches a single project by id. Use the expand parameter to inline related objects, such as the project owner, in one round-trip.

Path & query parameters for GET /v3/projects/{id}
Parameter	Type	Description
idrequired	string	The project id, e.g. prj_8Kd2 (in the path).
expand	array	Related objects to inline, e.g. ['owner', 'usage'].

RequestcURL

GET /v3/projects/{id}bash

curl https://api.aperture.dev/v3/projects/prj_8Kd2 \
  -H "Authorization: Bearer sk_live_•••"

Response200 OK

application/jsonjson

{
  "id": "prj_8Kd2",
  "object": "project",
  "name": "Aperture",
  "status": "active",
  "owner": "usr_3Lp9"
}

Delete a project

DELETE/v3/projects/{id}

Permanently deletes a project and schedules its data for removal. This cannot be undone; the call is idempotent and returns the deleted marker.

Path parameters for DELETE /v3/projects/{id}
Parameter	Type	Description
idrequired	string	The id of the project to delete (in the path).

RequestcURL

DELETE /v3/projects/{id}bash

curl -X DELETE https://api.aperture.dev/v3/projects/prj_8Kd2 \
  -H "Authorization: Bearer sk_live_•••"

Response200 OK

application/jsonjson

{
  "id": "prj_8Kd2",
  "object": "project",
  "deleted": true
}

Create a webhook endpoint

POST/v3/webhooks

Registers a URL to receive events. Aperture signs every delivery with the returned secret; verify the signature header before trusting the body.

Body parameters for POST /v3/webhooks
Parameter	Type	Description
urlrequired	string	An HTTPS URL that will receive POSTed events.
eventsrequired	array	Event types to subscribe to, e.g. ['project.created'].
description	string	An optional label shown in the dashboard.

RequestcURL

POST /v3/webhooksbash

curl -X POST https://api.aperture.dev/v3/webhooks \
  -H "Authorization: Bearer sk_live_•••" \
  -d '{ "url": "https://app.acme.com/hooks", "events": ["project.created"] }'

Response201 Created

application/jsonjson

{
  "id": "whk_2Qe7",
  "object": "webhook",
  "url": "https://app.acme.com/hooks",
  "secret": "whsec_•••",
  "status": "enabled"
}

Status codes

Aperture uses conventional HTTP status codes. 2xx means success, 4xx means the request was at fault, and 5xx means we were — and is always safe to retry.

HTTP status codes returned by the Aperture API
Code	Name	Meaning
200	OK	The request succeeded.
201	Created	A new resource was created.
304	Not Modified	A conditional GET matched — use your cache.
400	Bad Request	The request was malformed or missing a field.
401	Unauthorized	No valid API key was provided.
404	Not Found	The resource does not exist.
409	Conflict	An idempotency key was reused with a different body.
429	Too Many Requests	You hit a rate limit — back off and retry.
500	Server Error	Something went wrong on our end. Safe to retry.