Macroscope Workspaces API

openapi: 3.2.0
info:
  title: Macroscope Agent Webhook Workspaces API
  version: v1
  description: Inbound webhook API that triggers Macroscope's agent programmatically over HTTP.
  contact:
    name: Macroscope Support
    email: support@macroscope.com
    url: https://docs.macroscope.com/contact
  x-provenance:
    generated: '2026-07-20'
    method: generated
    source: https://docs.macroscope.com/api.md
servers:
- url: https://hooks.macroscope.com
  description: Macroscope agent webhook host
security:
- webhookSecret: []
tags:
- name: Workspaces
paths:
  /api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger:
    post:
      operationId: queryAgentWebhookTrigger
      summary: Trigger the agent
      description: POST a query to the agent. Returns 202 Accepted with a job token and poll URL. Optionally deliver the result to a Slack channel/thread or an allowlisted external webhook URL; omit responseDestination to retrieve the result by polling. Requires that Status is configured and backfill has finished.
      security:
      - webhookSecret: []
      parameters:
      - name: workspaceType
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerRequest'
      responses:
        '202':
          description: Query accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerAccepted'
        '400':
          description: Malformed request or missing query.
        '401':
          description: Missing or invalid X-Webhook-Secret.
        '403':
          description: Wrong workspace, or webhook URL not allowlisted.
      tags:
      - Workspaces
  /api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-jobs:
    get:
      operationId: pollAgentJob
      summary: Poll for an agent job result
      description: 'Poll for the result of a triggered job. Send the jobToken returned by the trigger as an Authorization: Bearer header. While running the response carries a Retry-After header (seconds). The job token is valid for about one hour.'
      security:
      - jobToken: []
      parameters:
      - name: workspaceType
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Job finished (completed or failed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResult'
        '202':
          description: Still running; retry after the Retry-After interval.
          headers:
            Retry-After:
              description: Seconds to wait before polling again.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: running
        '401':
          description: Missing or invalid job token.
        '403':
          description: Job token expired, or doesn't match this workspace.
        '404':
          description: Job not found.
      tags:
      - Workspaces
components:
  schemas:
    TriggerRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: The question to ask the agent.
        responseDestination:
          type: object
          description: Where to deliver the results. Omit to retrieve by polling.
          properties:
            slackChannelId:
              type: string
            slackThreadTs:
              type: string
            webhookUrl:
              type: string
              description: Must be an allowlisted HTTPS URL.
        timezone:
          type: string
          description: IANA timezone (e.g. America/Los_Angeles). Affects date references in the query.
    JobResult:
      type: object
      properties:
        status:
          type: string
          enum:
          - completed
          - failed
        response:
          type: string
    TriggerAccepted:
      type: object
      properties:
        jobToken:
          type: string
          description: Signed token (valid ~1 hour) authorizing you to read this one job's result.
        pollUrl:
          type: string
          description: Where to poll for the result.
        workflowId:
          type: string
          deprecated: true
  securitySchemes:
    webhookSecret:
      type: apiKey
      in: header
      name: X-Webhook-Secret
      description: Per-webhook API key created in Settings -> Connections -> Webhooks. Shown once and cannot be retrieved later.
    jobToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived (about one hour) signed job token returned by the trigger, authorizing reads of that one job's result.