openapi: 3.0.3
info:
  title: APIContext Platform API
  description: >-
    APIContext (formerly APImetrics) Platform API for synthetic API testing,
    monitoring, conformance, and SLO enforcement. Provides programmatic control
    over API calls, schedules, agents, monitors, results, statistics, insights,
    alerts, and reports.
  version: "2.0.0"
  contact:
    name: APIContext
    url: https://apicontext.com/
servers:
  - url: https://client.apimetrics.io/api/2
    description: APIContext production API
security:
  - ApiTokenAuth: []
components:
  securitySchemes:
    ApiTokenAuth:
      type: apiKey
      in: query
      name: _token
paths:
  /calls/:
    get:
      tags: [API Calls]
      operationId: listApiCalls
      summary: List API calls
      description: List all API calls configured in the account. API calls define the synthetic transactions APIContext executes against monitored APIs.
      responses:
        "200":
          description: List of API calls.
    post:
      tags: [API Calls]
      operationId: createApiCall
      summary: Create an API call
      description: Create a new API call (synthetic transaction definition) including target URL, method, headers, and validation rules.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created.
  /calls/{call_id}:
    get:
      tags: [API Calls]
      operationId: getApiCall
      summary: Get an API call
      description: Retrieve the configuration for a single API call by id.
      parameters:
        - name: call_id
          in: path
          required: true
          schema:
            type: string
          description: API call id.
      responses:
        "200":
          description: API call.
    put:
      tags: [API Calls]
      operationId: updateApiCall
      summary: Update an API call
      description: Update the definition of an existing API call.
      parameters:
        - name: call_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Updated.
    delete:
      tags: [API Calls]
      operationId: deleteApiCall
      summary: Delete an API call
      description: Delete an API call definition.
      parameters:
        - name: call_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted.
  /calls/{call_id}/run:
    post:
      tags: [API Calls]
      operationId: runApiCall
      summary: Trigger an API call
      description: Trigger an immediate synthetic execution of an API call from a chosen monitoring location.
      parameters:
        - name: call_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                location_id:
                  type: string
                  description: Monitoring agent location id (e.g. apimetrics_awsafsouth1).
                run_delay:
                  type: integer
                  description: Delay in seconds before executing the call.
      responses:
        "202":
          description: Run accepted.
  /calls/{call_id}/stats/:
    get:
      tags: [Statistics]
      operationId: getCallStats
      summary: Get statistics for an API call
      description: Return aggregated performance statistics (latency, availability, SLO compliance) for an API call over a time window.
      parameters:
        - name: call_id
          in: path
          required: true
          schema:
            type: string
        - name: kind
          in: query
          schema:
            type: string
            enum: [HOUR, DAY, WEEK, MONTH]
          description: Aggregation granularity.
        - name: type
          in: query
          schema:
            type: string
          description: Statistic type filter (e.g. ALL).
      responses:
        "200":
          description: Statistics payload.
  /results/call/{call_id}/:
    get:
      tags: [Results]
      operationId: getCallResults
      summary: Get raw performance results
      description: Return raw per-execution result records for an API call, including timing breakdowns, status codes, response bodies, and validation outcomes.
      parameters:
        - name: call_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Result records.
  /insights/call/{call_id}/:
    get:
      tags: [Insights]
      operationId: getCallInsights
      summary: Get insights report for an API call
      description: Return the APIContext insights report for an API call - SLO compliance, regressions, anomalies, and recommended actions.
      parameters:
        - name: call_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Insights report.
  /schedules/:
    get:
      tags: [Schedules]
      operationId: listSchedules
      summary: List schedules
      description: List monitoring schedules that control how often API calls are executed and from which regions.
      responses:
        "200":
          description: Schedules.
    post:
      tags: [Schedules]
      operationId: createSchedule
      summary: Create a schedule
      description: Create a monitoring schedule (frequency + regions) that can be attached to API calls.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                meta:
                  type: object
                schedule:
                  type: object
                  properties:
                    regions:
                      type: array
                      items:
                        type: string
                    frequency:
                      type: integer
      responses:
        "201":
          description: Created.
  /schedules/{schedule_id}:
    get:
      tags: [Schedules]
      operationId: getSchedule
      summary: Get a schedule
      description: Retrieve a monitoring schedule by id.
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Schedule.
    delete:
      tags: [Schedules]
      operationId: deleteSchedule
      summary: Delete a schedule
      description: Delete a monitoring schedule.
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted.
  /schedules/{schedule_id}/call/{call_id}:
    put:
      tags: [Schedules]
      operationId: addCallToSchedule
      summary: Add an API call to a schedule
      description: Attach an API call to a monitoring schedule so it executes on that cadence and across the schedule's configured regions.
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
        - name: call_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Linked.
    delete:
      tags: [Schedules]
      operationId: removeCallFromSchedule
      summary: Remove an API call from a schedule
      description: Detach an API call from a monitoring schedule.
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
        - name: call_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Detached.
  /agents/info:
    get:
      tags: [Agents]
      operationId: getAgentInfo
      summary: Get agent info
      description: Return the catalog of APIContext monitoring agents (regions, providers, capabilities) available for synthetic testing.
      responses:
        "200":
          description: Agent info.
  /agents/:
    get:
      tags: [Agents]
      operationId: listAgents
      summary: List agents
      description: List available monitoring agents (regions, providers) that can execute synthetic API calls.
      responses:
        "200":
          description: Agents.
  /projects/:
    get:
      tags: [Projects]
      operationId: listProjects
      summary: List projects
      description: List APIContext projects that group API calls, schedules, alerts, and tokens.
      responses:
        "200":
          description: Projects.
    post:
      tags: [Projects]
      operationId: createProject
      summary: Create a project
      description: Create a new APIContext project to group related API calls and monitors.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created.
  /projects/{project_id}:
    get:
      tags: [Projects]
      operationId: getProject
      summary: Get a project
      description: Retrieve a project by id.
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Project.
    put:
      tags: [Projects]
      operationId: updateProject
      summary: Update a project
      description: Update project metadata or configuration.
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Updated.
  /alerts/:
    get:
      tags: [Alerts]
      operationId: listAlerts
      summary: List alerts
      description: List alert rules configured against API calls and SLOs.
      responses:
        "200":
          description: Alerts.
    post:
      tags: [Alerts]
      operationId: createAlert
      summary: Create an alert
      description: Create a new alert rule (thresholds for latency, availability, SLO breach, response validation failure) and target channels.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created.
  /alerts/{alert_id}:
    get:
      tags: [Alerts]
      operationId: getAlert
      summary: Get an alert
      description: Retrieve an alert rule by id.
      parameters:
        - name: alert_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Alert.
    delete:
      tags: [Alerts]
      operationId: deleteAlert
      summary: Delete an alert
      description: Delete an alert rule.
      parameters:
        - name: alert_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted.
  /reports/:
    get:
      tags: [Reports]
      operationId: listReports
      summary: List reports
      description: List generated SLO and performance reports.
      responses:
        "200":
          description: Reports.
  /reports/{report_id}:
    get:
      tags: [Reports]
      operationId: getReport
      summary: Get a report
      description: Retrieve a generated SLO or performance report by id.
      parameters:
        - name: report_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Report.
  /directory/providers:
    get:
      tags: [Directory]
      operationId: listDirectoryProviders
      summary: List API directory providers
      description: List API providers tracked in the APIContext public API directory (300+ top providers) with current performance data for benchmarking.
      responses:
        "200":
          description: Directory providers.
  /directory/providers/{provider_id}:
    get:
      tags: [Directory]
      operationId: getDirectoryProvider
      summary: Get an API directory provider
      description: Retrieve performance data and metadata for a single provider in the APIContext API directory.
      parameters:
        - name: provider_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Provider record.
  /tokens/:
    get:
      tags: [Tokens]
      operationId: listTokens
      summary: List API tokens
      description: List API tokens issued for the current account.
      responses:
        "200":
          description: Tokens.
    post:
      tags: [Tokens]
      operationId: createToken
      summary: Create an API token
      description: Issue a new API token scoped to the requesting account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created.
  /tokens/{token_id}:
    delete:
      tags: [Tokens]
      operationId: deleteToken
      summary: Revoke an API token
      description: Revoke an issued API token.
      parameters:
        - name: token_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Revoked.
  /workflows/:
    get:
      tags: [Workflows]
      operationId: listWorkflows
      summary: List workflows
      description: List multi-step API workflows that chain calls together to exercise end-to-end business transactions.
      responses:
        "200":
          description: Workflows.
    post:
      tags: [Workflows]
      operationId: createWorkflow
      summary: Create a workflow
      description: Create a multi-step API workflow combining several API calls into one synthetic transaction.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created.
  /workflows/{workflow_id}:
    get:
      tags: [Workflows]
      operationId: getWorkflow
      summary: Get a workflow
      description: Retrieve a workflow definition by id.
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Workflow.
    put:
      tags: [Workflows]
      operationId: updateWorkflow
      summary: Update a workflow
      description: Update a multi-step API workflow.
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Updated.
  /workflows/{workflow_id}/run:
    post:
      tags: [Workflows]
      operationId: runWorkflow
      summary: Run a workflow
      description: Execute a multi-step API workflow on demand from a chosen monitoring location.
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "202":
          description: Accepted.