Antimetal Issues API

openapi: 3.2.0
info:
  title: Antimetal External Issues API
  description: Public-facing API for external integrations with Antimetal. Provides programmatic access to issue investigation, results, artifacts, and chat functionality.
  version: '2026-03-17'
  contact: {}
servers:
- url: https://bff.antimetal.com/api/v2
  description: Production API
- url: https://bff.dev.antimetal.com/api/v2
  description: Dev API
security:
- bearer: []
tags:
- name: Issues
paths:
  /issues:
    post:
      description: Creates a new issue and optionally starts an automated investigation. The issue is created from the provided details, with a seed generated internally. Investigation runs asynchronously - poll GET /issues/{id} to check status.
      operationId: createIssue
      parameters:
      - $ref: '#/components/parameters/AntimetalVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIssueDto'
      responses:
        '201':
          description: Issue created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateIssueResponseDto'
        '400':
          description: Validation error or bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
      summary: Create a new issue
      tags:
      - Issues
      x-codeSamples:
      - lang: JavaScript
        source: "import Antimetal from '@antimetal/sdk';\n\nconst client = new Antimetal({\n  apiKey: process.env['ANTIMETAL_API_KEY'], // This is the default and can be omitted\n});\n\nconst issue = await client.issues.create({\n  description: 'x',\n  environment: 'x',\n  title: 'x',\n});\n\nconsole.log(issue.uuid);"
    get:
      description: Returns a paginated list of issues for the authenticated organization
      operationId: listIssues
      parameters:
      - $ref: '#/components/parameters/AntimetalVersion'
      - name: limit
        required: false
        in: query
        description: Number of items to return (1-100)
        schema:
          minimum: 1
          maximum: 100
          default: 10
          type: integer
      - name: startingAfter
        required: false
        in: query
        description: Cursor for forward pagination (ID/UUID to start after)
        schema:
          type: string
      - name: endingBefore
        required: false
        in: query
        description: Cursor for backward pagination (ID/UUID to end before)
        schema:
          type: string
      - name: status
        required: false
        in: query
        description: Filter by issue status
        schema:
          type: string
          enum:
          - investigating
          - ready_to_fix
          - resolved
          - muted
      - name: environment
        required: false
        in: query
        description: Filter by environment (exact match)
        schema:
          minLength: 1
          type: string
      - name: search
        required: false
        in: query
        description: Search issues by title or description (case-insensitive substring match)
        schema:
          minLength: 1
          type: string
      responses:
        '200':
          description: Paginated list of issues
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IssueSummaryDto'
                  has_more:
                    type: boolean
                  after:
                    type: string
                  before:
                    type: string
                required:
                - object
                - data
                - has_more
        '400':
          description: Validation error or bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
      summary: Fetch issues for an organization
      tags:
      - Issues
      x-codeSamples:
      - lang: JavaScript
        source: "import Antimetal from '@antimetal/sdk';\n\nconst client = new Antimetal({\n  apiKey: process.env['ANTIMETAL_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const issueListResponse of client.issues.list()) {\n  console.log(issueListResponse.uuid);\n}"
  /issues/by_number/{number}:
    get:
      description: Lightweight endpoint to retrieve basic issue information by issue number
      operationId: getIssueByNumber
      parameters:
      - $ref: '#/components/parameters/AntimetalVersion'
      - name: number
        required: true
        in: path
        description: Issue number (organization-scoped)
        schema:
          type: integer
          format: int32
          minimum: 1
          example: 123
      responses:
        '200':
          description: Issue details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueDto'
        '404':
          description: Issue not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal Server Error
      summary: Fetch issue by number
      tags:
      - Issues
      x-codeSamples:
      - lang: JavaScript
        source: "import Antimetal from '@antimetal/sdk';\n\nconst client = new Antimetal({\n  apiKey: process.env['ANTIMETAL_API_KEY'], // This is the default and can be omitted\n});\n\nconst issue = await client.issues.retrieveByNumber(123);\n\nconsole.log(issue.uuid);"
  /issues/{id}:
    get:
      description: Retrieves detailed information about a specific issue by its ID (UUID)
      operationId: getIssue
      parameters:
      - $ref: '#/components/parameters/AntimetalVersion'
      - name: version
        required: false
        in: query
        description: Issue version (defaults to latest)
        schema:
          type: integer
          format: int32
          minimum: 1
      - name: id
        required: true
        in: path
        description: Issue unique identifier (UUID)
        schema:
          type: string
          format: uuid
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      responses:
        '200':
          description: Issue details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueDto'
        '400':
          description: Validation error or bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
      summary: Fetch an issue by ID (UUID)
      tags:
      - Issues
      x-codeSamples:
      - lang: JavaScript
        source: "import Antimetal from '@antimetal/sdk';\n\nconst client = new Antimetal({\n  apiKey: process.env['ANTIMETAL_API_KEY'], // This is the default and can be omitted\n});\n\nconst issue = await client.issues.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(issue.uuid);"
    patch:
      description: Updates the status of an existing issue by its ID (UUID)
      operationId: updateIssueStatus
      parameters:
      - $ref: '#/components/parameters/AntimetalVersion'
      - name: id
        required: true
        in: path
        description: Issue unique identifier (UUID)
        schema:
          type: string
          format: uuid
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIssueStatusDto'
      responses:
        '200':
          description: Updated issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueDto'
        '400':
          description: Validation error or bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
      summary: Update issue status by ID (UUID)
      tags:
      - Issues
      x-codeSamples:
      - lang: JavaScript
        source: "import Antimetal from '@antimetal/sdk';\n\nconst client = new Antimetal({\n  apiKey: process.env['ANTIMETAL_API_KEY'], // This is the default and can be omitted\n});\n\nconst issue = await client.issues.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n  status: 'investigating',\n});\n\nconsole.log(issue.uuid);"
    delete:
      description: Permanently deletes an issue and all associated data
      operationId: deleteIssue
      parameters:
      - $ref: '#/components/parameters/AntimetalVersion'
      - name: id
        required: true
        in: path
        description: Issue unique identifier (UUID)
        schema:
          type: string
          format: uuid
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      responses:
        '204':
          description: Issue deleted successfully
        '400':
          description: Validation error or bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
      summary: Delete an issue
      tags:
      - Issues
      x-codeSamples:
      - lang: JavaScript
        source: "import Antimetal from '@antimetal/sdk';\n\nconst client = new Antimetal({\n  apiKey: process.env['ANTIMETAL_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.issues.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');"
  /issues/{id}/results:
    get:
      description: Retrieves detailed investigation results including root cause analysis and remediation steps
      operationId: getIssueResults
      parameters:
      - $ref: '#/components/parameters/AntimetalVersion'
      - name: version
        required: false
        in: query
        description: Issue version for workflow results (defaults to latest)
        schema:
          type: integer
          format: int32
          minimum: 1
      - name: id
        required: true
        in: path
        description: Issue unique identifier (UUID)
        schema:
          type: string
          format: uuid
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      responses:
        '200':
          description: Investigation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueResultsDto'
        '400':
          description: Validation error or bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
      summary: Fetch investigation results by ID (UUID)
      tags:
      - Issues
      x-codeSamples:
      - lang: JavaScript
        source: "import Antimetal from '@antimetal/sdk';\n\nconst client = new Antimetal({\n  apiKey: process.env['ANTIMETAL_API_KEY'], // This is the default and can be omitted\n});\n\nconst result = await client.issues.results.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(result.sessionUuid);"
components:
  schemas:
    ErrorResponseDto:
      type: object
      properties:
        type:
          type: string
          enum:
          - api_error
          - invalid_request_error
          - authentication_error
          description: Error type classification
        message:
          type: string
          description: Human-readable error message
        request_id:
          type: string
          description: Request correlation ID for tracing and support
        details:
          description: Detailed field-level validation errors (for 400/422 responses)
          type: object
          additionalProperties:
            type: string
      required:
      - type
      - message
      - request_id
    IssueResultsDto:
      type: object
      properties:
        sessionUuid:
          description: Session UUID for live investigation
          type:
          - string
          - 'null'
        rootCause:
          description: Root cause information
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
              description: Root cause identifier
            incidentOverview:
              type: string
              description: Root cause problem overview
            rootCauseSummary:
              type: string
              description: Root cause analysis summary
            relevantEvidence:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                    description: Evidence title
                  status:
                    type: string
                    enum:
                    - relevant
                    - irrelevant
                    - inconclusive
                    description: Evidence status
                  description:
                    type: string
                    description: Evidence description
                  confidence:
                    type: string
                    enum:
                    - unknown
                    - unclear
                    - probable
                    - likely
                    - confirmed
                    description: Evidence confidence level
                  artifacts:
                    type: array
                    items:
                      type: object
                      properties:
                        documentId:
                          type: string
                          description: Document identifier for artifact fetching
                        title:
                          type: string
                          description: Artifact title
                        description:
                          type: string
                          description: Artifact description
                        dataType:
                          type: string
                          description: Type of data in this artifact
                      required:
                      - documentId
                      - title
                      - description
                      - dataType
                    description: Evidence artifacts with document references
                required:
                - title
                - status
                - description
                - confidence
                - artifacts
              description: Relevant evidence supporting the root cause
            irrelevantEvidence:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                    description: Evidence title
                  status:
                    type: string
                    enum:
                    - relevant
                    - irrelevant
                    - inconclusive
                    description: Evidence status
                  description:
                    type: string
                    description: Evidence description
                  confidence:
                    type: string
                    enum:
                    - unknown
                    - unclear
                    - probable
                    - likely
                    - confirmed
                    description: Evidence confidence level
                  artifacts:
                    type: array
                    items:
                      type: object
                      properties:
                        documentId:
                          type: string
                          description: Document identifier for artifact fetching
                        title:
                          type: string
                          description: Artifact title
                        description:
                          type: string
                          description: Artifact description
                        dataType:
                          type: string
                          description: Type of data in this artifact
                      required:
                      - documentId
                      - title
                      - description
                      - dataType
                    description: Evidence artifacts with document references
                required:
                - title
                - status
                - description
                - confidence
                - artifacts
              description: Irrelevant evidence ruled out during investigation
          required:
          - id
          - incidentOverview
          - rootCauseSummary
          - relevantEvidence
          - irrelevantEvidence
        causalTree:
          type: object
          properties:
            nodes:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for this node.
                  type:
                    type: string
                    enum:
                    - validated
                    - needs-context
                    - ruled-out
                    description: Node type indicating its state in the causal analysis
                  title:
                    type: string
                    description: Short title of the node
                  description:
                    type: string
                    description: Detailed description of the node
                  expandedContent:
                    description: Optional rich text content in Markdown format providing detailed explanation
                    type: string
                required:
                - id
                - type
                - title
                - description
            edges:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for this edge
                  source:
                    type: string
                    description: ID of the source node
                  target:
                    type: string
                    description: ID of the target node
                required:
                - id
                - source
                - target
          required:
          - nodes
          - edges
          description: Causal tree analysis
        causalTreeV2:
          type: object
          properties:
            nodes:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for this node in the causal graph (causal variable) e.g. db_connection_error or deployment_change.
                  title:
                    type: string
                    description: 'Brief display name for the causal variable. Use active verbs to show causal flow. CAUSE nodes: action-focused (e.g., ''Flag Activates Bad Store Routing'', ''Deployment Introduces Memory Leak''). MEDIATOR nodes: consequence-focused (e.g., ''Requests Routed to Invalid Endpoint'', ''Memory Exhaustion Occurs''). OUTCOME nodes: consequence-focused (e.g., ''Service Errors Exceed Threshold'', ''Response Times Degrade Beyond SLA''). Keep under 8 words.'
                  description:
                    type: string
                    description: 'Succinct explanation (1-2 sentences, ~30 words) describing what the underlying evidence shows and the node''s role in the incident. Use technical precision: include service names, error codes, field names, file paths. Use direct factual statements without explanations. Skip discovery details - focus on what happened, not how it was found. Include causal mechanism if relevant. Example: ''Configuration shows paymentFailure flag enabled at 12.5% rate, implementing probabilistic failure injection via Math.random() in charge.js:37.'' Let evidence documents contain detailed data.'
                  confidence:
                    type: string
                    enum:
                    - unknown
                    - unclear
                    - probable
                    - likely
                    - confirmed
                    description: Confidence in this node's role in the incident (e.g., how certain we are that this factor accurately represents what happened)
                  nodeType:
                    type: string
                    enum:
                    - outcome
                    - cause
                    - confounder
                    - mediator
                    description: 'Role in the causal graph: OUTCOME = the problem you''re investigating, CAUSE = what triggered it, CONFOUNDER = external factor affecting multiple variables, MEDIATOR = intermediate step in the causal path'
                  evidence:
                    type: array
                    items:
                      type: object
                      properties:
                        documentId:
                          type: string
                          description: Unique identifier for the document that contains this evidence (e.g., 'log:datadog:a9c1319258284740a7e5704134d90238', 'trace:gcp:abc123', 'file:github:24192d3b6c1292fd29da76ada910c175')
                        title:
                          type: string
                          minLength: 1
                          description: Human-readable name for this piece of evidence (e.g., 'Unbounded Cache Growth in recommendation_server.py', 'Deployment memory limit configuration','Deploy Script v2.1')
                        description:
                          type: string
                          minLength: 1
                          description: Direct factual statement about what the evidence shows and why it's relevant to the causal relationship (e.g., 'Shows 300% CPU spike at 14:23, correlating with error rate increase')
                        dataType:
                          type: string
                          description: Type of artifact extracted from documentId (log, metric, trace, file, etc.)
                      required:
                      - documentId
                      - title
                      - description
                      - dataType
                required:
                - id
                - title
                - description
                - confidence
                - nodeType
                - evidence
            edges:
              type: array
              items:
                type: object
                properties:
                  from:
                    type: string
                    description: Unique identifier for the source node in the causal graph.
                  to:
                    type: string
                    description: Unique identifier for the target node in the causal graph.
                  confidence:
                    type: number
                    minimum: 0
                    maximum: 1
                    description: Edge confidence reflects how certain we are about the causal relationship itself (e.g. how confident we are that the deployment caused the memory leak).
                required:
                - from
                - to
                - confidence
          required:
          - nodes
          - edges
          description: Causal graph V2 with enriched evidence
        remediation:
          type: object
          properties:
            actions:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Action identifier
                  uuid:
                    type: string
                    description: Action UUID
                  title:
                    type: string
                    description: Action title
                  description:
                    description: Optional action description
                    type: string
                  category:
                    description: 'Remediation category: immediate (quick stabilization), root_cause (fixes underlying issue), preventative (prevents recurrence)'
                    type: string
                    enum:
                    - immediate
                    - root_cause
                    - preventative
                  steps:
                    type: array
                    items:
                      oneOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            description: Step identifier
                          title:
                            type: string
                            description: Step title
                          helpMarkdown:
                            description: Optional help text in markdown
                            type: string
                          required:
                            type: boolean
                            description: Whether this step is required
                          label:
                            description: Optional label for the step
                            type: string
                          type:
                            type: string
                            description: Info step type
                            enum:
                            - info
                          content:
                            type: string
                            description: Markdown content to display
                        required:
                        - id
                        - title
                        - required
                        - type
                        - content
                      - type: object
                        properties:
                          id:
                            type: string
                            description: Step identifier
                          title:
                            type: string
                            description: Step title
                          helpMarkdown:
                            description: Optional help text in markdown
                            type: string
                          required:
                            type: boolean
                            description: Whether this step is required
                          label:
                            description: Optional label for the step
                    

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/antimetal/refs/heads/main/openapi/antimetal-issues-api-openapi.yml