openapi: 3.1.0
info:
  title: Traceable Platform GraphQL API
  description: The Traceable Platform API provides programmatic access to the Traceable API security and observability platform. The API enables querying of discovered API endpoints, vulnerability data, threat activity, entity analytics, and API security test suite configuration. Authentication uses a platform API token passed in the Authorization header. The platform exposes both a GraphQL API and REST endpoints for API specification downloads and MCP server access.
  version: '1.0'
  contact:
    name: Traceable Support
    url: https://docs.traceable.ai
  termsOfService: https://www.traceable.ai
servers:
- url: https://api.traceable.ai
  description: Traceable Production API
security:
- bearerAuth: []
tags:
- name: GraphQL
  description: Execute GraphQL queries against the Traceable platform for advanced analytics, entity queries, and bulk data retrieval.
paths:
  /graphql:
    post:
      operationId: executeGraphQLQuery
      summary: Execute GraphQL Query
      description: Executes a GraphQL query or mutation against the Traceable platform. Supports queries for entities, vulnerabilities, threat activity, explore datasets, API testing data, analytics batches, and authentication hooks. Use the Authorization header with your platform API token.
      tags:
      - GraphQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
      responses:
        '200':
          description: GraphQL query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '400':
          description: Invalid GraphQL query syntax
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /mcp:
    post:
      operationId: executeMCPTool
      summary: Execute MCP Tool
      description: Executes a tool via the Traceable MCP (Model Context Protocol) server. The MCP server exposes 12 tools for AI-assisted security workflows including attribute mappings, GraphQL query templates, threat activity time ranges, vulnerability filter values, sensitive data type details, and trend data calculation.
      tags:
      - GraphQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPRequest'
      responses:
        '200':
          description: MCP tool executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPResponse'
        '400':
          description: Invalid tool call
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GraphQLRequest:
      type: object
      description: A GraphQL query or mutation request.
      required:
      - query
      properties:
        query:
          type: string
          description: The GraphQL query or mutation string.
        variables:
          type: object
          description: Variables to pass to the GraphQL query.
          additionalProperties: true
        operationName:
          type: string
          description: Name of the operation to execute when multiple are defined.
    MCPRequest:
      type: object
      description: An MCP tool invocation request.
      required:
      - tool
      properties:
        tool:
          type: string
          description: 'Name of the MCP tool to execute. Available tools include: get_attribute_mappings, get_graphql_query_template_details, execute_graphql_query, get_query_time_range, get_threat_activity_timerange, get_vuln_enum_filter_supported_values, get_datatypes_details_from_datatype_names, get_datatypes_details_from_datatype_ids, calculate_trend_data, get_display_urls.'
          enum:
          - get_attribute_mappings
          - get_graphql_query_template_details
          - execute_graphql_query
          - get_query_time_range
          - get_threat_activity_timerange
          - get_vuln_enum_filter_supported_values
          - get_datatypes_details_from_datatype_names
          - get_datatypes_details_from_datatype_ids
          - calculate_trend_data
          - get_display_urls
        parameters:
          type: object
          description: Parameters for the tool call.
          additionalProperties: true
    Error:
      type: object
      description: Standard error response from the Traceable API.
      properties:
        error:
          type: string
          description: Error type identifier.
        message:
          type: string
          description: Human-readable error description.
        statusCode:
          type: integer
          description: HTTP status code.
    MCPResponse:
      type: object
      description: Result of an MCP tool execution.
      properties:
        result:
          type: object
          description: Tool execution result data.
          additionalProperties: true
        error:
          type: string
          description: Error message if the tool execution failed.
    GraphQLResponse:
      type: object
      description: A GraphQL response containing data or errors.
      properties:
        data:
          type: object
          description: The GraphQL response data.
          additionalProperties: true
        errors:
          type: array
          description: List of GraphQL errors if any occurred.
          items:
            type: object
            properties:
              message:
                type: string
              locations:
                type: array
                items:
                  type: object
                  properties:
                    line:
                      type: integer
                    column:
                      type: integer
              path:
                type: array
                items:
                  type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Platform API token generated through the Traceable dashboard. Pass as a Bearer token in the Authorization header. Tokens are single-use and cannot be retrieved after initial generation.
externalDocs:
  description: Traceable API Documentation
  url: https://docs.traceable.ai/docs/public-apis