Docs · API
Dorsal API
Search the Dorsal graph over HTTPS. You get the same records the Dorsal MCP server returns, from the same code: dated events with source links, named objects, and documentation passages. Your agent does the reasoning. Dorsal returns records.
Get a key
Paste this into the shell that runs your agent or script.
Preparing your install command with a trial key…Read-only, 150 requests a minute, lasts 30 days. Keep it out of code and chat.
Using Claude Code or Codex? The Dorsal skill installs the key and a client script in one command.
Quickstart
1. Search. Each kind is ranked and capped separately.
curl -s https://api.dorsal.us/v1/summaries \
-H "Authorization: Bearer $DORSAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "PgBouncer transaction pooling prepared statements", "total": 10}'{
"query": "PgBouncer transaction pooling prepared statements",
"by_kind": { "events": 10, "objects": 10, "documentation_chunks": 10 },
"total_returned": 30,
"results": [
{
"id": "…",
"kind": "event",
"event_type": "problem_discovered",
"description": "…",
"timestamp": "2026-10-30T13:41:31Z",
"source_type": "github_issue",
"url": "https://github.com/…"
}
]
}2. Fetch the records that decide your answer, at most 25 ids per call.
curl -s https://api.dorsal.us/v1/set \
-H "Authorization: Bearer $DORSAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ids": ["<id from summaries>", "<another id>"]}'3. Cite what you use by its source_url and date. Every event and passage carries both.
How it works
| Step | Endpoint | What you get |
|---|---|---|
| Search | POST /v1/summaries | Ranked events, named objects and documentation chunks for a query, each with an id, a description, a date and a source URL. |
| Read | POST /v1/set | Full records for exact ids: an event's source text and reported details, a full documentation passage, or an object profile. |
| Traverse | POST /v1/neighbors | One object's relationships, such as makers, alternatives and dependencies. Set include_events to list its events. |
Retrieval is deterministic. No LLM runs between the graph and your agent. Your agent judges the records with your project context.
Three more endpoints return methods your agent can follow: GET /v1/protocols/dorsal?mode=investigate (or mode=improve) for a “dorsal …” request, GET /v1/protocols/decision-verification for checking a decision, and GET /v1/protocols/audit for auditing recent work in a repository. GET /v1 lists every endpoint with its body schema.
POST /v1/summaries
| Field | Type | Notes |
|---|---|---|
query | string, required | Topic, task, model, constraint or use-case phrase. |
total | integer 1–100 | Items per kind. Default 50; start with 10. |
page_size | integer 1–25 | Turns on paging. Follow next_cursor while it is present. |
cursor | string | next_cursor from the previous page. Repeat the query and filters unchanged. |
event_types | string[] | Filters events. capability_observed returns measured model results. |
object_types | string[] | Filters objects. |
sources | string[] | Filters events and documentation. docs returns documented product behavior. |
since until | ISO date | Bounds dated events and documentation. Objects are unfiltered. |
Event types
decision_madeinsight_discoveredaction_takenoutcome_appearedproblem_discoveredproblem_solvedworkaround_sharedcapability_changedcapability_observedgoal_setidea_or_plan_proposedinformation_source_discoveredfunding_eventjob_changepartnership_announcedevent_announcedproduct_releasedproduct_updatedrelease_publishedpr_openedpr_mergedpr_closedissue_filedissue_closedreddit_postdoc_addeddoc_removeddoc_renamedotherObject types
product_or_servicemethodproblemuse_caserepoorganizationpersonSources
docsgithubgithub_issuegithub_prgithub_releasegithub_docreddit_postblog_postyoutube_videodiscord_threadtwitter_threadpodcast_transcriptpodcast_episodeacademic_paperhackernews_threadwebweb_pagecase_studyforum_postpress_releasestatus_pagePOST /v1/set
{ "ids": ["…"] } with 1 to 25 ids from summaries or neighbors. Returns { requested, found, results }. An unknown id comes back as { "id": "…", "found": false }. Ids are opaque labels: pass them back unchanged and read an event's type from its event_type field.
POST /v1/neighbors
| Field | Type | Notes |
|---|---|---|
query | string, required | Object name or alias, or an event or documentation chunk id. |
include_events | boolean | Adds the object's source-linked events. |
hops | 1, 2 or 3 | Default 1. |
direction | out, in, both | Default both. |
total | integer 1–100 | Per section. Default 50. |
target_type rel_type | string[] | Narrow connected objects or relationship types. |
An unknown name returns { "error": "no object matched" } with HTTP 200. Take the exact name or id from a summaries result.
GET /v1/protocols/audit
Returns the current audit method. Your agent reads the repository locally, follows the method, and sends Dorsal only generalized searches. Every query parameter is optional.
| Parameter | Values | Notes |
|---|---|---|
phase | audit, fix | Default audit. Request fix after the user approves one change. |
sections | core, memory, remediation_boundary, support, all | Comma-separated. Default core for audit; core, remediation_boundary and support for fix. |
client | claude-code-skill, codex-skill, claude-code-prompt, other-mcp | Names your integration. |
Errors
Every non-200 response carries { "error": { "type", "message" } }, and the message names the field and the fix.
| Status | Type | What to do |
|---|---|---|
| 400 | invalid_request_error | Fix the field the message names and retry. |
| 400 | privacy_block | The query held a file path, URL, key, email, setting or private host. Dorsal refused it and stored nothing. Rewrite it with public names. |
| 401 | authentication_error | The key is missing, wrong or expired. Get a new one above. |
| 404 · 405 | not_found_error | Wrong path or method. GET /v1 lists the endpoints. |
| 429 | rate_limit_error | Wait the Retry-After seconds. |
| 503 | overloaded_error | Dorsal is busy or restarting. Wait the Retry-After seconds. |
Limits and privacy
25 ids per /v1/set call, 100 items per kind, 2 MB per request body. Trial keys allow 150 requests a minute and last 30 days.
Everything you send leaves your machine. Send short searches in public names: products, models, libraries, versions and error types. Keep code, file paths, keys, config values, commit history and customer data local.
When an agent calls the API, give it the skill and its dorsal.sh instead of raw curl. The script checks every request on your machine before sending it and refuses file paths, keys, URLs, emails, private hosts, and names, branches, commit text and .env values from the repository you work in. Raw curl sends whatever it is given.
The server refuses queries with file paths, URLs, keys, emails, settings or private hosts, answers 400 privacy_block, and keeps no copy of the refused text.