Currents Spec Files API

openapi: 3.2.0
info:
  title: Currents Dev Spec Files API
  version: 1.0.0
  contact:
    name: Currents Support
    url: https://currents.dev
  description: 'Operations tagged Spec Files across 2 of this provider''s published API definitions: currents-dev-openapi.json, currents-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.currents.dev/v1
  description: Production API
- url: https://api-staging.currents.dev/v1
  description: Staging API
- url: http://localhost:4000/v1
  description: Local development
security:
- BearerAuth: []
tags:
- name: Spec Files
  description: 'Query spec file metrics and statistics.


    Get aggregated metrics for spec files within a project, including execution counts,

    failure rates, flakiness rates, and duration statistics.'
paths:
  /spec-files/{projectId}/metrics:
    get:
      summary: Get spec file metrics
      description: 'Duration percentiles, the duration histogram and the failure and flakiness rates for the spec files matching the filters, over the date range and the range of the same length before it. Pass `signature` for a single spec file. The filters and `includeFailedInDuration` behave as they do on `GET /spec-files/{projectId}`, so the numbers agree with the rows there. One difference from the list: a spec file that ran only in the previous range still counts toward `previous`, so the comparison describes what the previous range actually held.'
      operationId: getSpecFilesMetrics
      security:
      - BearerAuth: []
      - OAuth2:
        - analytics:read
      tags:
      - Spec Files
      parameters:
      - $ref: '#/components/parameters/ProjectIdPath'
      - $ref: '#/components/parameters/DateStartQuery'
      - $ref: '#/components/parameters/DateEndQuery'
      - $ref: '#/components/parameters/TagsQuery'
      - $ref: '#/components/parameters/BranchesQuery'
      - $ref: '#/components/parameters/GroupsQuery'
      - $ref: '#/components/parameters/AuthorsQuery'
      - $ref: '#/components/parameters/EnvironmentsQuery'
      - name: signature
        in: query
        required: false
        description: Limit the metrics to one spec file
        schema:
          type: string
          minLength: 1
      - name: spec_name_filter
        in: query
        required: false
        description: Filter spec files by name (partial match). The camelCase `specNameFilter` that `GET /spec-files/{projectId}` takes is accepted too, so one query string drives the list and its metrics.
        schema:
          type: string
          minLength: 1
      - name: include_failed_in_duration
        in: query
        required: false
        description: Include failed executions in the duration calculation. The camelCase `includeFailedInDuration` is accepted too.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                  data:
                    $ref: '#/components/schemas/MetricsSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.currents.dev/v1
      description: Production API
    - url: https://api-staging.currents.dev/v1
      description: Staging API
    - url: http://localhost:4000/v1
      description: Local development
  /spec-files/{projectId}:
    get:
      summary: Get spec files
      description: Get spec file metrics and statistics for a project within a date range
      operationId: getSpecFiles
      security:
      - BearerAuth: []
      - OAuth2:
        - analytics:read
      tags:
      - Spec Files
      parameters:
      - $ref: '#/components/parameters/ProjectIdPath'
      - $ref: '#/components/parameters/DateStartQuery'
      - $ref: '#/components/parameters/DateEndQuery'
      - $ref: '#/components/parameters/PageQuery'
      - $ref: '#/components/parameters/SpecFilesLimitQuery'
      - $ref: '#/components/parameters/TagsQuery'
      - $ref: '#/components/parameters/BranchesQuery'
      - $ref: '#/components/parameters/GroupsQuery'
      - $ref: '#/components/parameters/AuthorsQuery'
      - $ref: '#/components/parameters/EnvironmentsQuery'
      - name: order
        in: query
        required: false
        description: Field to order results by
        schema:
          type: string
          enum:
          - avgDuration
          - failedExecutions
          - failureRate
          - flakeRate
          - flakyExecutions
          - fullyReported
          - overallExecutions
          - suiteSize
          - timeoutExecutions
          - timeoutRate
          default: avgDuration
      - $ref: '#/components/parameters/SortDirectionQuery'
      - name: specNameFilter
        in: query
        required: false
        description: Filter spec files by name (partial match)
        schema:
          type: string
      - name: includeFailedInDuration
        in: query
        required: false
        description: Include failed executions in duration calculation
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpecFilesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.currents.dev/v1
      description: Production API
    - url: https://api-staging.currents.dev/v1
      description: Staging API
    - url: http://localhost:4000/v1
      description: Local development
components:
  parameters:
    ProjectIdPath:
      name: projectId
      in: path
      required: true
      description: The project ID
      schema:
        type: string
      example: proj_abc123
    GroupsQuery:
      name: groups[]
      in: query
      required: false
      description: Filter by groups (can be specified multiple times using bracket notation, e.g., groups[]=group1&groups[]=group2)
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
      example:
      - group1
      - group2
    TagsQuery:
      name: tags[]
      in: query
      required: false
      description: Filter by tags (can be specified multiple times using bracket notation, e.g., tags[]=value1&tags[]=value2)
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
      example:
      - tag1
      - tag2
    EnvironmentsQuery:
      name: environments[]
      in: query
      required: false
      description: Filter by environment (can be specified multiple times using bracket notation, e.g., environments[]=staging&environments[]=production)
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
      example:
      - staging
      - production
    SpecFilesLimitQuery:
      name: limit
      in: query
      required: false
      description: 'Maximum number of items to return (default: 50, max: 50)'
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 50
    DateEndQuery:
      name: date_end
      in: query
      required: true
      description: End date in ISO 8601 format
      schema:
        type: string
        format: date-time
      example: '2024-01-31T23:59:59.999Z'
    PageQuery:
      name: page
      in: query
      required: false
      description: Page number (0-indexed)
      schema:
        type: integer
        minimum: 0
        default: 0
    BranchesQuery:
      name: branches[]
      in: query
      required: false
      description: Filter by git branch. Use trailing `*` for prefix match (e.g. `release/*`). Max 250 characters per value.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/BranchFilterQueryValue'
      style: form
      explode: true
      example:
      - main
      - release/*
    AuthorsQuery:
      name: authors[]
      in: query
      required: false
      description: Filter by git authors (can be specified multiple times using bracket notation, e.g., authors[]=author1&authors[]=author2)
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
      example:
      - author1
      - author2
    DateStartQuery:
      name: date_start
      in: query
      required: true
      description: Start date in ISO 8601 format
      schema:
        type: string
        format: date-time
      example: '2024-01-01T00:00:00.000Z'
    SortDirectionQuery:
      name: dir
      in: query
      required: false
      description: 'Sort direction: `desc` (default) or `asc`.'
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
  schemas:
    BranchFilterQueryValue:
      description: 'Branch filter value: an exact branch name, or a trailing `*` for prefix match (e.g. `release/*`). Max 250 characters.'
      oneOf:
      - type: string
        description: Exact branch name (must not contain `*` or spaces).
        pattern: ^[!-)+-~]+$
        maxLength: 250
      - type: string
        description: 'Prefix match: branch prefix followed by `*`.'
        pattern: ^[!-)+-~]+\*$
        maxLength: 250
    SpecFile:
      type: object
      properties:
        signature:
          type: string
          description: Unique spec file signature
        spec:
          type: string
          description: Spec file path
        metrics:
          type: object
          properties:
            avgDuration:
              type: number
              description: Average duration in milliseconds
            failedExecutions:
              type: integer
            failureRate:
              type: number
            flakeRate:
              type: number
            flakyExecutions:
              type: integer
            fullyReported:
              type: integer
            overallExecutions:
              type: integer
            suiteSize:
              type: integer
            timeoutExecutions:
              type: integer
            timeoutRate:
              type: number
    MetricsSummary:
      type: object
      description: Duration percentiles and outcome rates for a selection of tests or spec files, plus the duration histogram.
      required:
      - current
      - previous
      - minMs
      - maxMs
      - distribution
      properties:
        current:
          $ref: '#/components/schemas/PeriodMetrics'
        previous:
          allOf:
          - $ref: '#/components/schemas/PeriodMetrics'
          description: The range of the same length before the one asked for.
        minMs:
          type:
          - number
          - 'null'
          description: Shortest execution in the current range.
        maxMs:
          type:
          - number
          - 'null'
          description: Longest execution in the current range.
        distribution:
          type: array
          description: Executions per duration bucket, in the current range. Buckets widen with duration; empty buckets between the first and last are included.
          items:
            type: object
            required:
            - minMs
            - maxMs
            - executions
            properties:
              minMs:
                type: number
              maxMs:
                type: number
              executions:
                type: number
    ErrorResponse:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: string
          enum:
          - FAILED
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Stable machine-readable discriminator, present on refusals a client is expected to branch on (for example `AI_CONSENT_REQUIRED`). The `error` text is free-form; branch on `code`.
        candidates:
          type: array
          description: 'With `code: ambiguous_target`: the runs, spec files or tests the request matched. Send one of their IDs.'
          items:
            type: object
            properties:
              runId:
                type: string
              ciBuildId:
                type: string
              instanceId:
                type: string
              groupId:
                type: string
              spec:
                type: string
              machineId:
                type:
                - string
                - 'null'
              testId:
                type: string
              title:
                type: array
                items:
                  type: string
    PeriodMetrics:
      type: object
      required:
      - executions
      - overallExecutions
      - avgMs
      - p50Ms
      - p90Ms
      - p95Ms
      - passRate
      - failureRate
      - flakinessRate
      - suiteSize
      - testsPerExecution
      properties:
        executions:
          type: number
          description: Executions the duration metrics are calculated over. Narrower than `overallExecutions` when the average-duration metric setting excludes a status.
        overallExecutions:
          type: number
          description: Executions the rates are calculated over.
        avgMs:
          type:
          - number
          - 'null'
        p50Ms:
          type:
          - number
          - 'null'
        p90Ms:
          type:
          - number
          - 'null'
        p95Ms:
          type:
          - number
          - 'null'
        passRate:
          type:
          - number
          - 'null'
          description: Rate as a 0-1 float. Tests only.
        failureRate:
          type:
          - number
          - 'null'
          description: Rate as a 0-1 float. Failures are failed and interrupted executions together.
        flakinessRate:
          type:
          - number
          - 'null'
        suiteSize:
          type:
          - number
          - 'null'
          description: Tests in the most recent execution of a spec file. Null unless the metrics describe a single spec file.
        testsPerExecution:
          type:
          - number
          - 'null'
          description: Average tests per spec execution. Spec files only.
    SpecFilesResponse:
      type: object
      required:
      - status
      - data
      properties:
        status:
          type: string
          enum:
          - OK
        data:
          type: object
          properties:
            list:
              type: array
              items:
                $ref: '#/components/schemas/SpecFile'
            total:
              type: integer
              description: Total number of spec files
            nextPage:
              oneOf:
              - type: integer
              - type: boolean
              description: Next page number or false if no more pages
  responses:
    Forbidden:
      description: 'The credential authenticated but is not permitted to use this endpoint. Five refusals share the status: a `read` API key on an endpoint that writes, an OAuth token that was not granted the scope the endpoint needs (`insufficient_scope`), an OAuth token that was granted it but whose holder no longer has a role permitting it (`insufficient_role`), an OAuth token on an endpoint that accepts an API key and nothing else (`api_key_required`), and an API key on an endpoint that answers for a user (`user_credential_required`). Discriminate on `code` rather than on the message, which is free-form. The first refusal predates the codes and sets none. Only `insufficient_scope` carries the challenge header, because it is the only one a client can act on by re-authorizing.'
      headers:
        WWW-Authenticate:
          description: 'Present on the `insufficient_scope` refusal only, naming the scope to re-authorize for (RFC 6750 3.1): `Bearer error="insufficient_scope", scope="webhooks:read"`. Absent on `insufficient_role`, where the scope is already granted, and on `api_key_required` and `user_credential_required`, where no scope would help.'
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            apiKeyIsReadOnly:
              summary: A read API key on an endpoint that writes
              value:
                status: FAILED
                error: 'Insufficient permissions: write access required'
            scopeNotGranted:
              summary: An OAuth token missing the endpoint's scope
              value:
                status: FAILED
                error: 'Insufficient permissions: this endpoint requires the webhooks:read scope'
                code: insufficient_scope
            scopeAboveRole:
              summary: An OAuth token holding the scope, whose holder was since demoted
              value:
                status: FAILED
                error: 'Insufficient permissions: the webhooks:write scope requires the admin role in this organization'
                code: insufficient_role
            apiKeyRequired:
              summary: An OAuth token on an endpoint that takes an API key
              value:
                status: FAILED
                error: This endpoint accepts an API key, not an OAuth access token
                code: api_key_required
            userCredentialRequired:
              summary: An API key on an endpoint that answers for a user
              value:
                status: FAILED
                error: This endpoint requires an OAuth access token or a personal access token; an API key belongs to an organization, not a user
                code: user_credential_required
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: FAILED
            error: Invalid authentication credentials
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: FAILED
            error: 'Invalid request body: name is required'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: FAILED
            error: Not found
  securitySchemes:
    RecordKey:
      type: apiKey
      in: header
      name: x-currents-key
      description: An organization's record key, the one a reporter sends. Accepted only by the two attachment routes under `/runs`, `POST /runs/{runId}/context-links`, `POST /sessions`, `POST /sessions/{sessionId}/attachments` and, for a session, `POST /share`, so a CI job can attach files, link its failed and flaky tests, record a session and share it with the key it already has.
    BearerAuth:
      type: http
      scheme: bearer
      description: 'An organization API key, sent as `Authorization: Bearer <key>`. A key carries one scope for the whole API: a `read` key reaches the GET endpoints, a `write` key reaches all of them. A `crnts_pat_` personal access token is accepted as a Bearer while its owner remains an eligible administrator in its active organization. Each operation requires the corresponding scope stored on that token.'
    OAuth2:
      type: oauth2
      description: 'An access token from the Currents authorization server, for an application acting as a user in one organization. Unlike an API key it is confined per endpoint: the operation lists the scope it needs, and a token that was not granted that scope gets 403.


        **The endpoints below are production''s.** They are written out so this specification can be exercised against production, and they are wrong for every other deployment — a token minted by `id.currents.dev` is refused by a staging or on-premise API, whose `OAUTH_ISSUER` and `OAUTH_API_AUDIENCE` are its own. Against anything but production, and in a client generated from this document, discover them instead: `GET {api origin}/.well-known/oauth-protected-resource`, then the `authorization_servers[0]` document.


        **The audience named here is the REST API''s.** `POST /mcp` is a second resource server on the same origin, identified by `{api origin}/mcp` and described by its own document at `/.well-known/oauth-protected-resource/mcp`. Every operation below refuses a token minted for it, and it refuses every token minted for these, so a client of this specification wants the audience above and not that one.'
      flows:
        authorizationCode:
          authorizationUrl: https://id.currents.dev/api/auth/oauth2/authorize
          tokenUrl: https://id.currents.dev/api/auth/oauth2/token
          refreshUrl: https://id.currents.dev/api/auth/oauth2/token
          scopes:
            projects:read: See which projects exist and their names
            projects:write: Change project configuration, including a project's tags
            results:read: See runs, specs and failure detail — errors, stacks and artifacts
            analytics:read: 'See aggregate metrics: flake and failure rates, error counts, durations and trends'
            actions:read: See quarantine and skip rules, and the tests they affect
            actions:write: Create, edit, enable, disable and archive quarantine and skip rules
            issues:write: Create and link issues in a connected issue tracker, and list its projects and issue types
            runs:write: Cancel and reset runs, and permanently delete runs and their artifacts
            webhooks:read: See webhook configuration, including destination URLs and headers
            webhooks:write: Create, edit and delete webhooks
            shares:write: Create public links to test results that anyone with the link can open until they expire
x-refined-from:
- currents-dev-openapi.json
- currents-dev-openapi.yml