Overview
Auth
- POSTCreate a new API key for the authenticated tenant.
- GETList all API keys for the authenticated tenant.
- GETGet details of a specific API key.
- POSTRotate an API key. Creates a new key and revokes the old one.
- DELRevoke an API key. The key is immediately invalidated.
- GETGet information about the authenticated tenant.
- PATCHUpdate tenant information (name).
- GETList audit log entries for the authenticated tenant.
- POSTCreate a Stripe Checkout session for tenant provisioning.
- GETRetrieve a provisioned API key after Stripe Checkout. The claim token (checkout session ID) acts as the access credential. One-time retrieval only — the key cannot be shown again.
- POSTPost apiv1authmagic linkrequest
- POSTPost apiv1authmagic linkverify
Contacts
- GETList contacts with optional filtering by kind, search query, and pagination.
- POSTCreate a new contact.
- GETGet a contact by ID with all related data (channels, addresses, dates, tags, affiliations).
- PUTUpdate a contact.
- DELSoft-delete a contact.
- GETFind a contact by communication channel (type + value).
- POSTAdd a communication channel to a contact.
- DELRemove a communication channel from a contact.
- POSTAdd a postal address to a contact.
- PUTUpdate a postal address.
- DELRemove a postal address from a contact.
- POSTAdd a significant date to a contact (birthday, anniversary, etc.).
- PUTUpdate a significant date.
- DELRemove a significant date from a contact.
- GETList relationships for a contact.
- POSTAdd a relationship between two contacts.
- DELRemove a relationship.
- GETList organizational affiliations for a contact.
- POSTAdd an organizational affiliation to a contact.
- DELRemove an organizational affiliation.
- GETList interactions for a contact.
- POSTLog an interaction with a contact.
- POSTAdd a tag to a contact.
- DELRemove a tag from a contact.
- GETList all contact tag definitions for the tenant.
- POSTCreate a new contact tag definition.
- GETList all contact groups for the tenant.
- POSTCreate a new contact group.
- DELDelete a contact group.
- GETList members of a contact group.
- POSTAdd a contact to a group.
- DELRemove a contact from a group.
- GETList all relationship types for the tenant.
CRM
- GETList all CRM pipelines with their stages.
- POSTCreate a new pipeline, optionally with initial stages.
- GETGet a pipeline by ID with its stages.
- PUTUpdate a pipeline.
- DELDelete a pipeline (soft delete).
- POSTSet a pipeline as the default.
- GETList stages in a pipeline.
- POSTCreate a new stage in a pipeline.
- PUTReorder stages in a pipeline.
- PUTUpdate a stage.
- DELDelete a stage from a pipeline.
- GETGet a pipeline summary with deal counts and values per stage.
- GETList deals with optional filtering.
- POSTCreate a new deal.
- GETGet a deal by ID with pipeline, stage, and contact details.
- PUTUpdate a deal.
- DELDelete a deal (soft delete).
- POSTMove a deal to a different stage. Records a stage change audit entry.
- GETGet stage change history for a deal.
- GETList contacts associated with a deal.
- POSTAssociate a contact with a deal.
- DELRemove a contact from a deal.
- POSTAdd a tag to a deal.
- DELRemove a tag from a deal.
- GETList all CRM tag definitions.
- POSTCreate a new CRM tag definition.
Tasks
- GETList projects with optional filtering.
- POSTCreate a new project.
- GETGet a project by ID with statuses, sections, milestones, and counts.
- PUTUpdate a project.
- DELDelete a project (soft delete).
- GETList custom statuses for a project.
- POSTAdd a custom status to a project.
- PUTUpdate a project status.
- DELRemove a status from a project.
- GETList sections in a project.
- POSTAdd a section to a project.
- PUTUpdate a project section.
- DELRemove a section from a project.
- GETList milestones in a project.
- POSTAdd a milestone to a project.
- PUTUpdate a milestone.
- DELRemove a milestone.
- GETList members of a project.
- POSTAdd a member to a project.
- DELRemove a member from a project.
- GETList tasks with optional filtering.
- POSTCreate a new task.
- GETGet a task by ID with labels, dependency/link/comment counts.
- PUTUpdate a task.
- DELDelete a task (soft delete).
- GETGet a task by its human-readable identifier (e.g., PROJ-42).
- GETList overdue tasks.
- POSTMark a task as complete.
- POSTCancel a task.
- GETList subtasks of a task.
- GETList dependencies of a task.
- POSTAdd a dependency to a task.
- DELRemove a dependency from a task.
- GETList comments on a task.
- POSTAdd a comment to a task.
- PUTUpdate a task comment.
- POSTAdd a label to a task.
- DELRemove a label from a task.
- GETList cross-domain links for a task.
- POSTAdd a cross-domain link to a task.
- DELRemove a cross-domain link from a task.
- GETList all task label definitions for the tenant.
- POSTCreate a new task label definition.
Calendar
- GETList calendars for the authenticated tenant.
- POSTCreate a new calendar.
- GETGet a calendar by ID.
- PUTUpdate a calendar.
- DELDelete a calendar (soft delete).
- GETList events with optional filtering by date range, calendar, and type.
- POSTCreate a new event.
- GETGet an event by ID with attendees and links.
- PUTUpdate an event.
- DELDelete an event (soft delete).
- GETFull-text search across events.
- POSTAdd an attendee to an event.
- PUTUpdate an attendee's RSVP status.
- DELRemove an attendee from an event.
- POSTAdd a cross-domain link to an event.
- DELRemove a cross-domain link from an event.
Notes
- GETList all notebooks for the tenant with note counts.
- POSTCreate a new notebook.
- GETGet a notebook by ID with note count.
- PUTUpdate a notebook.
- DELDelete a notebook (soft delete).
- GETList notes with optional filtering by notebook, tag, and search.
- POSTCreate a new note.
- GETGet a note by ID with tags and link counts.
- PUTUpdate a note.
- DELDelete a note (soft delete).
- GETList outgoing links from a note.
- POSTAdd a link from a note to another entity.
- DELRemove a link from a note.
- GETList notes that link to a given note (backlinks).
- GETList notes that link to any entity (cross-domain backlinks).
- POSTAdd a tag to a note (creates the tag if it does not exist).
- DELRemove a tag from a note.
- GETList attachments for a note.
- POSTAdd an attachment to a note.
- DELRemove an attachment from a note.
- GETList all note tag definitions for the tenant.
- POSTCreate a new note tag definition.
Members
- POSTCreate a new member within the tenant.
- GETList all members for the tenant.
- GETGet the authenticated member's own information.
- GETGet a member by ID.
- PATCHUpdate a member (name, email, role, active status, metadata).
- DELDeactivate a member (soft disable — sets is_active = false).
- PUTReplace all access policies for a member (PUT semantics).
- GETGet all access policies for a member.
- POSTCreate an API key linked to a specific member.
- POSTCreate an invitation for a new member.
- GETList all invitations for the tenant.
- DELRevoke a pending invitation.
- POSTClaim an invitation using a claim code. Public endpoint — no auth required. Returns the newly created member, an API key, and access policies.
Agents
- GETList all `agent_configs` rows for the current tenant.
- GETGet a single `agent_configs` row by kind.
- PUTUpsert the non-BYOK portion of an `agent_configs` row. Full-replace semantics — omitted fields revert to NULL / `[]`.
- DELDelete an `agent_configs` row. Does not cascade to `agent_runs` — historical run rows remain queryable.
- POSTProbe a candidate API key against Anthropic without persisting it. Used by the wizard path: the frontend validates a key before the user commits it. Always returns 200 — the `ProbeResult` body distinguishes valid from invalid.
- PUTSet (or rotate) the BYOK key for one agent kind. Orchestrates the probe → encrypt → store sequence in a single atomic call so a client that skips `validate-key` still gets a safe error on bad input.
- DELOperator revoke: wipes the ciphertext and pins `byok_status` to `revoked`. Sticky per the state machine — the tenant must re-enter a key (via `PUT /byok-key`) to return to active.
- GETList runs for an agent kind with cursor pagination and optional status filter. Newest-first.
- POSTEnqueue a new agent run. Returns the inserted row; the worker wakes via `NOTIFY agent_runs_new` (fired by the schema trigger on commit).
- GETFetch one run plus its journal steps (in seq order).
- POSTCancel a non-terminal run. No-op on already-terminal runs (returns 409).
Webhooks
- GETList all webhook endpoints.
- POSTCreate a new webhook endpoint. Returns signing secret once.
- GETGet a webhook endpoint by ID. Does not include signing secret.
- PUTUpdate a webhook endpoint.
- DELSoft-delete a webhook endpoint.
- POSTSend a test ping event to a webhook endpoint. Uses the same pinned-DNS + dual-sign + capped-body code path as the delivery worker so a successful test is a faithful dry run of production delivery.
- POSTRotate the signing secret for a webhook endpoint. Returns new secret once.
- GETList recent webhook events.
- GETGet a webhook event by ID with payload.
- POSTRetry delivery of a specific event to all matching active endpoints.
- POSTBulk recover failed events from a timestamp.
Billing & Usage
Fetch one run plus its journal steps (in seq order).
curl --request GET \
--url https://api.backside.app/api/v1/agents/{kind}/runs/{id} \
--header 'Authorization: Bearer <token>'{
"agent_kind": "<string>",
"consecutive_failures": 123,
"cost_usd_cents": 123,
"created_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"input": "<unknown>",
"platform_fee_cents": 123,
"run_at": "2023-11-07T05:31:56Z",
"status": "<string>",
"tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"updated_at": "2023-11-07T05:31:56Z",
"steps": [
{
"input": "<unknown>",
"kind": "<string>",
"name": "<string>",
"seq": 123,
"started_at": "2023-11-07T05:31:56Z",
"cache_read_tokens": 123,
"cache_write_tokens": 123,
"completed_at": "2023-11-07T05:31:56Z",
"cost_usd_cents": 123,
"input_tokens": 123,
"model": "<string>",
"output": "<unknown>",
"output_tokens": 123
}
],
"budget_usd_cents": 123,
"deadline_at": "2023-11-07T05:31:56Z",
"failure_category": "<string>",
"failure_detail": "<string>",
"output": "<unknown>"
}Agents
Fetch one run plus its journal steps (in seq order).
GET
/
api
/
v1
/
agents
/
{kind}
/
runs
/
{id}
Fetch one run plus its journal steps (in seq order).
curl --request GET \
--url https://api.backside.app/api/v1/agents/{kind}/runs/{id} \
--header 'Authorization: Bearer <token>'{
"agent_kind": "<string>",
"consecutive_failures": 123,
"cost_usd_cents": 123,
"created_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"input": "<unknown>",
"platform_fee_cents": 123,
"run_at": "2023-11-07T05:31:56Z",
"status": "<string>",
"tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"updated_at": "2023-11-07T05:31:56Z",
"steps": [
{
"input": "<unknown>",
"kind": "<string>",
"name": "<string>",
"seq": 123,
"started_at": "2023-11-07T05:31:56Z",
"cache_read_tokens": 123,
"cache_write_tokens": 123,
"completed_at": "2023-11-07T05:31:56Z",
"cost_usd_cents": 123,
"input_tokens": 123,
"model": "<string>",
"output": "<unknown>",
"output_tokens": 123
}
],
"budget_usd_cents": 123,
"deadline_at": "2023-11-07T05:31:56Z",
"failure_category": "<string>",
"failure_detail": "<string>",
"output": "<unknown>"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Response
Run with journal steps
GET /agents/{kind}/runs/{id} response — the run plus its journal
entries in seq order. Steps are flattened into a list; there are no
sub-resources yet (agent_step_payloads is internal; agent_events
is chunk 10+).
Show child attributes
Show child attributes
Was this page helpful?
Enqueue a new agent run. Returns the inserted row; the worker wakes
via `NOTIFY agent_runs_new` (fired by the schema trigger on commit).Cancel a non-terminal run. No-op on already-terminal runs (returns 409).
⌘I
Assistant
Responses are generated using AI and may contain mistakes.