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.

Your trial key

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.

Two more endpoints return methods your agent can follow: GET /v1/protocols/dorsal?mode=investigate (or mode=improve) for a “dorsal …” request, and GET /v1/protocols/decision-verification for checking a decision. 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_renamedother

Object types

product_or_servicemethodproblemuse_caserepoorganizationperson

Sources

docsgithubgithub_issuegithub_prgithub_releasegithub_docreddit_postblog_postyoutube_videodiscord_threadtwitter_threadpodcast_transcriptpodcast_episodeacademic_paperhackernews_threadwebweb_pagecase_studyforum_postpress_releasestatus_page

POST /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.

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.
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 generalized technical questions about public products, models, libraries and error patterns. Keep code, file paths, credentials and customer data local.