openapi: 3.1.0
info:
  title: Salesgraph REST OMS API
  description: 'The same GTM research and audit engine behind the Salesgraph MCP server, exposed as a small REST
    API under `/api/v1`. Command endpoints use API key authentication and return markdown (`Content-Type: text/markdown`)
    on success; OMS endpoints return JSON; errors are returned as JSON. Synchronous commands (research, competitors,
    help) return the markdown result inline; asynchronous audits (gtm-audit, audit) return a run id to poll. The
    OMS (Opportunity Management System) endpoints query the organization''s own visible sales objects, traverse
    their relationships, and manage continuous research watches. A separate unauthenticated Status API at `/api/status`
    publishes component health.

    '
  version: v1
  contact:
    name: Salesgraph Support
    email: support@salesgraph.com
    url: https://salesgraph.com/support
  x-provenance:
    generated: '2026-08-13'
    method: generated
    source: https://docs.salesgraph.com/reference/rest-api.md
    note: 'Faithfully modeled from the published Salesgraph REST API reference plus the provider''s own Agent Skill
      at docs.salesgraph.com/.well-known/agent-skills/salesgraph/skill.md. The provider''s docs.salesgraph.com/api-reference/openapi.json
      is STILL a Mintlify "OpenAPI Plant Store" placeholder (re-probed 2026-08-13, HTTP 200) and was NOT harvested.
      Round 2 added the OMS endpoints, the org-audit poll, and the public /api/status endpoint, all of which the
      provider documented after the round-1 pass.

      '
servers:
- url: https://salesgraph.com
  description: Production
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: OMS
  description: 'Opportunity Management System — query the organization''s visible sales objects, traverse their
    relationships, inspect provenance, and manage continuous research watches.

    '
paths:
  /api/v1/oms/metadata:
    get:
      operationId: getOmsMetadata
      summary: Get visible OMS metadata
      description: 'Returns the visible OMS ontology metadata — the object types, links, and properties the calling
        organization can see. Responses are JSON.

        '
      tags:
      - OMS
      responses:
        '200':
          description: Visible OMS ontology metadata.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/oms/search:
    post:
      operationId: searchOmsObjects
      summary: Search visible OMS objects
      description: 'Searches the visible OMS objects of one type. Returns a page of objects plus a `nextPageToken`
        to continue, or `null` when the page is the last one.

        '
      tags:
      - OMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OmsSearchRequest'
      responses:
        '200':
          description: A page of matching OMS objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OmsObjectPage'
        '400':
          $ref: '#/components/responses/OmsInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/OmsAccessDenied'
  /api/v1/oms/get:
    post:
      operationId: getOmsObject
      summary: Get one visible OMS object
      description: 'Fetches a single visible OMS object by its type and PUBLIC key (for example `domain:acme.com`)
        — not an internal primary key.

        '
      tags:
      - OMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OmsObjectRef'
      responses:
        '200':
          description: One OMS object.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/OmsInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/OmsAccessDenied'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/oms/pivot:
    post:
      operationId: pivotOmsObject
      summary: Traverse a visible OMS relationship
      description: 'Traverses a named link from one OMS object in a given direction — for example from an Account
        to its Opportunities. Returns a page of objects plus a `nextPageToken`.

        '
      tags:
      - OMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OmsPivotRequest'
      responses:
        '200':
          description: A page of linked OMS objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OmsObjectPage'
        '400':
          $ref: '#/components/responses/OmsInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/OmsAccessDenied'
  /api/v1/oms/provenance:
    post:
      operationId: getOmsProvenance
      summary: Get visible object provenance
      description: 'Returns the data lineage of one OMS object — its properties, relationships, and history, with
        the sources each came from.

        '
      tags:
      - OMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OmsObjectRef'
      responses:
        '200':
          description: Provenance for one OMS object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OmsProvenance'
        '400':
          $ref: '#/components/responses/OmsInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/oms/watches:
    get:
      operationId: listOmsWatches
      summary: List research watches
      description: 'Lists the manageable continuous research watches for the organization. Pass `id` to fetch a
        single watch. Returns `{ watches, nextCursor }`.

        '
      tags:
      - OMS
      parameters:
      - name: id
        in: query
        required: false
        description: Fetch a single watch by id instead of listing.
        schema:
          type: string
      responses:
        '200':
          description: A page of research watches (or one watch when `id` is supplied).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OmsWatchPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createOmsWatch
      summary: Create a research watch
      description: 'Creates a continuous research watch on an Account or Opportunity. Accepts an `idempotencyKey`
        so a retried create does not produce a duplicate watch. Frequencies run from `1h` through 30 days; `lite`
        watches require a monthly cost cap of at least 3000 micros and `base` watches at least 10000, both capped
        at 100000000. A source policy accepts up to 25 valid domains per include or exclude list, with no domain
        in both.

        '
      tags:
      - OMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OmsWatchRequest'
      responses:
        '200':
          description: The created watch object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OmsWatch'
        '400':
          $ref: '#/components/responses/OmsInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/OmsAccessDenied'
    delete:
      operationId: cancelOmsWatch
      summary: Cancel a research watch
      description: Cancels one manageable research watch by id.
      tags:
      - OMS
      parameters:
      - name: id
        in: query
        required: true
        description: The watch id to cancel.
        schema:
          type: string
      responses:
        '200':
          description: The cancelled watch object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OmsWatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/oms/actions:
    post:
      operationId: requestOmsAction
      summary: Request an approved OMS action
      description: 'Requests a human-approved OMS action — an opportunity update, a rep note, or a drafted follow-up
        email. Returns 202 with a JSON approval request; the action is not applied until a person approves it.

        '
      tags:
      - OMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: The action request payload.
      responses:
        '202':
          description: An approval request was created.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/OmsInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/OmsAccessDenied'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send your Salesgraph API key as `Authorization: Bearer sg_live_...`.'
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Alternative header — send your Salesgraph API key as `x-api-key: sg_live_...`.'
  responses:
    NotFound:
      description: Unknown command or run id (or an id belonging to another organization).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    OmsAccessDenied:
      description: The caller cannot see or manage the requested OMS resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: access_denied
    OmsInvalidInput:
      description: An OMS input validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_input
    Unauthorized:
      description: Missing, malformed, or revoked API key.
      headers:
        WWW-Authenticate:
          schema:
            type: string
            example: Bearer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: 'Machine-readable error code — `unauthorized`, `invalid_input`, `access_denied`, or `not_found`.

            '
    OmsObjectPage:
      type: object
      description: A page of OMS objects.
      properties:
        objects:
          type: array
          items:
            type: object
        nextPageToken:
          type:
          - string
          - 'null'
          description: Token for the next page, or null on the last page.
    OmsObjectRef:
      type: object
      required:
      - type
      - key
      description: A reference to one OMS object by type and PUBLIC key.
      properties:
        type:
          type: string
          description: The OMS object type (for example `Account` or `Opportunity`).
          example: Account
        key:
          type: string
          description: The public OMS key, not an internal primary key.
          example: domain:acme.com
    OmsPivotRequest:
      type: object
      required:
      - type
      - key
      - link
      - direction
      description: A traversal of one named OMS relationship.
      properties:
        type:
          type: string
        key:
          type: string
        link:
          type: string
          description: The relationship name to traverse.
        direction:
          type: string
          description: The direction to traverse the link in.
    OmsProvenance:
      type: object
      description: Data lineage for one OMS object.
      properties:
        properties:
          type: array
          items:
            type: object
        relationships:
          type: array
          items:
            type: object
        history:
          type: array
          items:
            type: object
    OmsSearchRequest:
      type: object
      required:
      - type
      description: A search over visible OMS objects of one type.
      properties:
        type:
          type: string
          description: The OMS object type to search.
        query:
          type: string
          description: The search query.
        pageToken:
          type: string
          description: Continuation token from a previous page.
    OmsSourcePolicy:
      type: object
      description: 'Optional domain allow/deny policy. Each list accepts up to 25 valid domains and a domain may
        not appear in both.

        '
      properties:
        includeDomains:
          type: array
          items:
            type: string
        excludeDomains:
          type: array
          items:
            type: string
    OmsWatch:
      type: object
      description: A continuous research watch.
      properties:
        id:
          type: string
        target:
          $ref: '#/components/schemas/OmsObjectRef'
        query:
          type: string
        frequency:
          type: string
        processor:
          type: string
        monthlyCostCapMicros:
          type: integer
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    OmsWatchPage:
      type: object
      description: A page of research watches.
      properties:
        watches:
          type: array
          items:
            $ref: '#/components/schemas/OmsWatch'
        nextCursor:
          type:
          - string
          - 'null'
          description: Cursor for the next page, or null on the last page.
    OmsWatchRequest:
      type: object
      required:
      - target
      - query
      - frequency
      - processor
      - monthlyCostCapMicros
      description: A request to create a continuous research watch.
      properties:
        target:
          $ref: '#/components/schemas/OmsObjectRef'
        query:
          type: string
          description: What to monitor.
        purpose:
          type: string
          description: Why the watch exists.
        idempotencyKey:
          type: string
          description: 'Caller-supplied key that makes a retried create safe — resubmitting the same key does not
            create a second watch.

            '
        frequency:
          type: string
          description: How often the watch runs, from `1h` through 30 days.
          example: 1d
        processor:
          type: string
          enum:
          - lite
          - base
          description: The processor tier, which sets the minimum monthly cost cap.
        sourcePolicy:
          $ref: '#/components/schemas/OmsSourcePolicy'
        monthlyCostCapMicros:
          type: integer
          description: 'Monthly cost cap in micros — at least 3000 for `lite`, at least 10000 for `base`, at most
            100000000 for either.

            '