Salesgraph Audit API

openapi: 3.1.0
info:
  title: Salesgraph REST Audit API
  description: 'The same GTM research and audit engine behind the Salesgraph MCP server, exposed as a small REST API under `/api/v1`. Every endpoint uses API key authentication and returns markdown (`Content-Type: text/markdown`) on success; 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.

    '
  version: v1
  contact:
    name: Salesgraph Support
    email: support@salesgraph.com
    url: https://salesgraph.com/support
  x-provenance:
    generated: '2026-07-21'
    method: generated
    source: https://docs.salesgraph.com/reference/rest-api.md
    note: 'Faithfully modeled from the published Salesgraph REST API reference. The provider''s own docs.salesgraph.com/api-reference/openapi.json is a Mintlify Plant Store placeholder and was NOT harvested; this spec captures the real documented /api/v1 surface.

      '
servers:
- url: https://salesgraph.com
  description: Production
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Audit
  description: The org audit shortcut.
paths:
  /api/v1/audit:
    post:
      operationId: startOrgAudit
      summary: Start the org audit shortcut
      description: 'Starts your org''s audit. By default returns 202 with a run id to poll. Pass `{"wait": true}` (or `?wait=true`) to block until the audit finishes — this can take several minutes and returns 504 if it exceeds the server timeout (the run keeps going).

        '
      tags:
      - Audit
      parameters:
      - name: wait
        in: query
        required: false
        description: Block until the audit finishes and return the result inline.
        schema:
          type: boolean
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                wait:
                  type: boolean
      responses:
        '200':
          description: Audit completed inline (when wait=true).
          content:
            text/markdown:
              schema:
                type: string
        '202':
          description: Async audit started; poll for the result.
          headers:
            X-Audit-Id:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '428':
          $ref: '#/components/responses/OnboardingRequired'
        '504':
          description: The synchronous wait exceeded the server timeout; the run keeps going — poll its id.
    get:
      operationId: pollOrgAudit
      summary: Poll an org audit by id
      description: Polls an existing org audit run by id.
      tags:
      - Audit
      parameters:
      - name: id
        in: query
        required: true
        description: The org audit run id.
        schema:
          type: string
      responses:
        '200':
          description: Audit status line or, once completed, the full result markdown.
          content:
            text/markdown:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    OnboardingRequired:
      description: Onboarding required — finish your org's sales profile before running audits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Unknown command or run id (or an id belonging to another organization).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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 (e.g. unauthorized).
  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_...`.'