Cogram Backup Runs API

openapi: 3.2.0
info:
  title: Cogram Backup Runs API
  description: 'API for integrating with Cogram. Every key is scoped to one organization.


    - **Auth**: `Authorization: Bearer `. Admins mint keys in Organization

    Settings → Integrations → API Keys.

    - **Pagination**: `page` (1-indexed) + `page_size` (default 50, max 100); returns

    `{"data": [...], "total": N, "page": N, "page_size": N}`. `total` = all matches.

    - **Errors**: `{"error": "", "message": ""}`. Branch on `error`; `message`

    wording may change.

    - **Rate limit**: per key, 1000 req/min by default. `429` carries `Retry-After`,

    `X-RateLimit-Limit`, `X-RateLimit-Remaining`.

    - **Attribution**: optional `X-Forwarded-User` header (≤200 chars) names the end user

    behind the call in Cogram''s audit trail.


    See API documentation for guides and examples.'
  version: v1
servers:
- url: /v1
tags:
- name: backup-runs
  description: Report backup runs so Cogram can alert when they stop.
paths:
  /backup-runs:
    post:
      tags:
      - backup-runs
      summary: Report a backup run
      description: 'Record that a backup run started or finished.


        Report `started` when a run begins and `finished` with a `status` when it

        ends. A `finished` run with `status: success` clears any outstanding

        stale-backup alert, so the next outage produces a fresh notification.'
      operationId: external_create_backup_run_route_backup_runs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackupRunCreateV1'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupRunV1'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorV1'
              example:
                error: api_key_invalid
                message: Invalid API key
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorV1'
              example:
                error: not_found
                message: Resource not found
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorV1'
              example:
                error: validation_error
                message: 'body -> name: Field required'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorV1'
              example:
                error: rate_limit_exceeded
                message: Rate limit exceeded. Please try again later.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorV1'
              example:
                error: internal_error
                message: An internal error occurred
      security:
      - HTTPBearer: []
components:
  schemas:
    BackupRunCreateV1:
      properties:
        event:
          $ref: '#/components/schemas/ConnectorBackupEvent'
          description: '`started` when a run begins, `finished` when it ends.'
        schedule_interval_hours:
          type: integer
          maximum: 8760.0
          minimum: 1.0
          title: Schedule Interval Hours
          description: The connector's configured interval between runs. Cogram measures backup health against this rather than a server-side setting, because only the connector knows its own schedule.
        status:
          anyOf:
          - $ref: '#/components/schemas/ConnectorBackupStatus'
          - type: 'null'
          description: Required on `finished`; must be omitted on `started`.
        projects_synced:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Projects Synced
          description: Projects filed by this run. Zero is a healthy result — a run with no changed projects exports nothing.
        error:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Error
          description: Failure detail. Only meaningful when `status` is `failed`.
      type: object
      required:
      - event
      - schedule_interval_hours
      title: BackupRunCreateV1
      description: One backup lifecycle event, reported by the connector.
    ConnectorBackupStatus:
      type: string
      enum:
      - success
      - failed
      title: ConnectorBackupStatus
      description: Outcome of a finished run. Absent on ``started`` events.
    ConnectorBackupEvent:
      type: string
      enum:
      - started
      - finished
      title: ConnectorBackupEvent
      description: Lifecycle point a connector reports.
    ErrorCode:
      type: string
      enum:
      - api_key_missing
      - api_key_invalid_format
      - api_key_invalid
      - api_key_expired
      - bad_request
      - forbidden
      - not_found
      - method_not_allowed
      - conflict
      - validation_error
      - rate_limit_exceeded
      - internal_error
      - range_too_large
      - data_export_in_progress
      title: ErrorCode
      description: Error codes for external API v1.
    ErrorV1:
      properties:
        error:
          $ref: '#/components/schemas/ErrorCode'
          description: Stable machine-readable code. Branch on this.
        message:
          type: string
          title: Message
          description: Human-readable detail. Wording may change.
      type: object
      required:
      - error
      - message
      title: ErrorV1
      description: 'JSON body format for all API v1 error responses.


        This model controls the actual serialization of error responses:

        {"error": "not_found", "message": "Project ''xyz'' not found"}'
    BackupRunV1:
      properties:
        id:
          type: string
          title: Id
        event:
          $ref: '#/components/schemas/ConnectorBackupEvent'
        status:
          anyOf:
          - $ref: '#/components/schemas/ConnectorBackupStatus'
          - type: 'null'
        schedule_interval_hours:
          type: integer
          title: Schedule Interval Hours
        projects_synced:
          anyOf:
          - type: integer
          - type: 'null'
          title: Projects Synced
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - event
      - status
      - schedule_interval_hours
      - projects_synced
      - error
      - created_at
      title: BackupRunV1
      description: A recorded backup lifecycle event.
  securitySchemes:
    HTTPBearer:
      type: http
      description: Organization API key. Minted by admins in Organization Settings → Integrations → API Keys; shown once, may carry an expiry.
      scheme: bearer
      bearerFormat: Cogram organization API key