Dorsal API

openapi: 3.1.0
info:
  title: Dorsal API
  version: '2026-11-10'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-10: 7 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Dorsal has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 1
    documentation: 6
    pages-with-code: 1
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-10'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://godorsal.com/docs/api
paths:
  /v1:
    get:
      operationId: get_v1
      tags:
      - Api
      summary: GET /v1 lists every endpoint with its body schema.
      x-source: https://godorsal.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/neighbors:
    post:
      operationId: post_v1_neighbors
      tags:
      - Neighbors
      summary: One object's relationships, such as makers, alternatives and dependencies.
      x-source: https://godorsal.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1NeighborsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1NeighborsResponse'
      x-evidence:
        kind: documentation
  /v1/protocols/audit:
    get:
      operationId: get_v1_protocols_audit
      tags:
      - Protocols
      summary: GET /v1/protocols/audit returns the current audit method.
      x-source: https://godorsal.com/docs/api
      parameters:
      - name: phase
        in: query
        required: false
        schema:
          type: string
        description: audit, fix (default audit).
      - name: sections
        in: query
        required: false
        schema:
          type: string
        description: Comma‑separated list of sections.
      - name: client
        in: query
        required: false
        schema:
          type: string
        description: Names your integration.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/protocols/decision-verification:
    get:
      operationId: get_v1_protocols_decision_verification
      tags:
      - Protocols
      summary: GET /v1/protocols/decision-verification for checking a decision.
      x-source: https://godorsal.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/protocols/dorsal:
    get:
      operationId: get_v1_protocols_dorsal
      tags:
      - Protocols
      summary: GET /v1/protocols/dorsal?mode=investigate (or mode=improve ) for a “dorsal …” request.
      x-source: https://godorsal.com/docs/api
      parameters:
      - name: mode
        in: query
        required: false
        schema:
          type: string
        description: investigate or improve
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/set:
    post:
      operationId: post_v1_set
      tags:
      - Set
      summary: 'Full records for exact ids: an event''s source text and reported details, a full documentation passage, or an object profile.'
      x-source: https://godorsal.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1SetRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1SetResponse'
      x-evidence:
        kind: documentation
  /v1/summaries:
    post:
      operationId: post_v1_summaries
      tags:
      - Summaries
      summary: POST /v1/summaries
      x-source: https://godorsal.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1SummariesRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1SummariesResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "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}' {\n \"query\": \"PgBouncer transaction pooling\
          \ prepared statements\",\n \"by_kind\": { \"events\": 10, \"objects\": 10, \"documentation_chunks\": 10 },\n \"total_returned\": 30,\n\
          \ \"results\": [\n {\n \"id\": \"…\",\n \"ki"
components:
  schemas:
    PostV1NeighborsRequest:
      type: object
      properties:
        query:
          type: string
          description: Object name or alias, or an event or documentation chunk id.
        include_events:
          type: boolean
          description: Adds the object's source‑linked events.
        hops:
          type: integer
          description: 1, 2 or 3. Default 1.
        direction:
          type: string
          description: out, in, both. Default both.
        total:
          type: integer
          description: 1–100 per section. Default 50.
        target_type:
          type: string
        rel_type:
          type: array
          description: string[] Narrow connected objects or relationship types.
      required:
      - query
    PostV1NeighborsResponse:
      type: object
      properties:
        error:
          type: string
          description: '"no object matched" if unknown name.'
    PostV1SetRequest:
      type: object
      properties:
        ids:
          type: array
          description: 1 to 25 ids from summaries or neighbors.
      required:
      - ids
    PostV1SetResponse:
      type: object
      properties:
        requested:
          type: integer
        found:
          type: integer
        results:
          type: array
    PostV1SummariesRequest:
      type: object
      properties:
        query:
          type: string
        total:
          type: integer
    PostV1SummariesResponse:
      type: object
      properties:
        id:
          type: string
        found:
          type: boolean
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Neighbors
- name: Protocols
- name: Set
- name: Summaries