openapi: 3.1.0
info:
  title: 786 Cyber API
  version: 1.0.0
  summary: Read your organisation's 786 Cyber data from your own tools.
  description: |
    Read-only access to findings, assets, scans, compliance status, evidence details, risks,
    people (opt-in) and the event feed that webhooks also send.

    **Authentication.** Create a key in Settings › Integrations › API keys and send it as
    `Authorization: Bearer 786_live_…`. Each key carries scopes; a call outside them gets 403.
    The organisation always comes from the key.

    **Paging and sync.** Lists return `{ "data": [...], "next_cursor": "…" | null }`, oldest change
    first. Pass `next_cursor` back as `cursor` until it is null. To sync, keep the last
    `updated_at` you saw and call again with `updated_since`.

    **Limits.** Up to 600 requests a minute per key (1,200 per organisation). Over that you get
    429 with `Retry-After`.

    **Findings** in the event feed follow OCSF 1.3.0 (see the webhooks guide).
  contact:
    name: 786 Cyber support
    url: https://786cyber.com/docs/api
servers:
  - url: https://786cyber.com/api/v1
security:
  - bearerAuth: []
tags:
  - name: Account
  - name: Findings
  - name: Assets
  - name: Scans
  - name: Compliance
  - name: Evidence
  - name: Risks
  - name: People
  - name: Events
paths:
  /me:
    get:
      tags: [Account]
      summary: The key you are calling with and its organisation
      operationId: getMe
      responses:
        '200':
          description: Key details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      org: { type: object, properties: { id: { type: string, format: uuid } } }
                      key:
                        type: object
                        properties:
                          id: { type: string, format: uuid }
                          name: { type: string }
                          scopes: { type: array, items: { type: string } }
                          expires_at: { type: [string, 'null'], format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /findings:
    get:
      tags: [Findings]
      summary: List findings
      description: 'Scope: `findings:read`.'
      operationId: listFindings
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/updated_since'
        - name: status
          in: query
          schema: { type: string, enum: [open, in_progress, awaiting_verification, pending_approval, exception, closed] }
        - name: severity
          in: query
          schema: { type: string, enum: [critical, high, medium, low, informational] }
        - name: asset_id
          in: query
          schema: { type: string, format: uuid }
      responses:
        '200': { description: A page of findings, content: { application/json: { schema: { $ref: '#/components/schemas/FindingPage' } } } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /findings/{id}:
    get:
      tags: [Findings]
      summary: One finding
      description: 'Scope: `findings:read`.'
      operationId: getFinding
      parameters: [{ $ref: '#/components/parameters/id' }]
      responses:
        '200': { description: The finding, content: { application/json: { schema: { type: object, properties: { data: { $ref: '#/components/schemas/Finding' } } } } } }
        '404': { $ref: '#/components/responses/NotFound' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /assets:
    get:
      tags: [Assets]
      summary: List assets
      description: 'Scope: `assets:read`. Retired assets are included with their status.'
      operationId: listAssets
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/updated_since'
        - name: type
          in: query
          description: Asset type, e.g. endpoint, hardware, network, domain, cloud, software_cloud.
          schema: { type: string }
      responses:
        '200': { description: A page of assets, content: { application/json: { schema: { $ref: '#/components/schemas/AssetPage' } } } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /assets/{id}:
    get:
      tags: [Assets]
      summary: One asset
      description: 'Scope: `assets:read`.'
      operationId: getAsset
      parameters: [{ $ref: '#/components/parameters/id' }]
      responses:
        '200': { description: The asset, content: { application/json: { schema: { type: object, properties: { data: { $ref: '#/components/schemas/Asset' } } } } } }
        '404': { $ref: '#/components/responses/NotFound' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /scans:
    get:
      tags: [Scans]
      summary: List scans
      description: 'Scope: `scans:read`.'
      operationId: listScans
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/updated_since'
      responses:
        '200': { description: A page of scans, content: { application/json: { schema: { $ref: '#/components/schemas/GenericPage' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /assessments:
    get:
      tags: [Compliance]
      summary: List framework assessments and their scores
      description: 'Scope: `compliance:read`.'
      operationId: listAssessments
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/updated_since'
      responses:
        '200': { description: A page of assessments, content: { application/json: { schema: { $ref: '#/components/schemas/GenericPage' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /controls:
    get:
      tags: [Compliance]
      summary: List control status
      description: 'Scope: `compliance:read`. One row per control your organisation has a status for.'
      operationId: listControls
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/updated_since'
      responses:
        '200': { description: A page of control statuses, content: { application/json: { schema: { $ref: '#/components/schemas/GenericPage' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /evidence:
    get:
      tags: [Evidence]
      summary: List evidence details
      description: 'Scope: `evidence:read`. Titles, types, tags and expiry only; never files or file names.'
      operationId: listEvidence
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/updated_since'
      responses:
        '200': { description: A page of evidence items, content: { application/json: { schema: { $ref: '#/components/schemas/GenericPage' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /risks:
    get:
      tags: [Risks]
      summary: List risks
      description: 'Scope: `risks:read`.'
      operationId: listRisks
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/updated_since'
      responses:
        '200': { description: A page of risks, content: { application/json: { schema: { $ref: '#/components/schemas/GenericPage' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /risks/{id}:
    get:
      tags: [Risks]
      summary: One risk
      description: 'Scope: `risks:read`.'
      operationId: getRisk
      parameters: [{ $ref: '#/components/parameters/id' }]
      responses:
        '200': { description: The risk, content: { application/json: { schema: { type: object, properties: { data: { type: object } } } } } }
        '404': { $ref: '#/components/responses/NotFound' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /people:
    get:
      tags: [People]
      summary: List people and their identity posture
      description: 'Scope: `people:read` (not ticked by default: it returns names and work emails).'
      operationId: listPeople
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/updated_since'
      responses:
        '200': { description: A page of people, content: { application/json: { schema: { $ref: '#/components/schemas/GenericPage' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /events:
    get:
      tags: [Events]
      summary: The event feed (the same events webhooks send)
      description: |
        Scope: `events:read`. For tools that poll instead of receiving webhooks. Events are kept
        30 days; each item is exactly the webhook body. `updated_since` filters on when the event
        was recorded.
      operationId: listEvents
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/updated_since'
        - name: type
          in: query
          description: Comma-separated event types, e.g. `finding.created,scan.failed`.
          schema: { type: string }
      responses:
        '200': { description: A page of events, content: { application/json: { schema: { $ref: '#/components/schemas/EventPage' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '`786_live_` followed by 43 characters.'
  parameters:
    id:
      name: id
      in: path
      required: true
      schema: { type: string, format: uuid }
    limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 500, default: 100 }
    cursor:
      name: cursor
      in: query
      description: '`next_cursor` from the previous page.'
      schema: { type: string }
    updated_since:
      name: updated_since
      in: query
      description: ISO 8601 date-time; only rows changed at or after it.
      schema: { type: string, format: date-time }
  responses:
    BadRequest: { description: A parameter is not valid, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    Unauthorized: { description: Missing, unknown, revoked or expired key, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    Forbidden: { description: 'The key lacks the scope, or the API is not included for the organisation', content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    NotFound: { description: Not found in your organisation, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    RateLimited:
      description: Too many requests
      headers: { Retry-After: { schema: { type: integer } } }
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code: { type: string }
            message: { type: string }
    Finding:
      type: object
      properties:
        id: { type: string, format: uuid }
        title: { type: string }
        description: { type: [string, 'null'] }
        severity: { type: string, enum: [critical, high, medium, low, informational] }
        status: { type: string, enum: [open, in_progress, awaiting_verification, pending_approval, exception, closed] }
        status_reason: { type: [string, 'null'] }
        remediation: { type: [string, 'null'] }
        cve_id: { type: [string, 'null'] }
        cvss_score: { type: [number, 'null'] }
        epss_score: { type: [number, 'null'] }
        known_exploited: { type: boolean, description: On the CISA KEV list }
        priority_score: { type: [integer, 'null'] }
        lane: { type: [string, 'null'] }
        asset_id: { type: [string, 'null'], format: uuid }
        scan_id: { type: string, format: uuid }
        first_seen_at: { type: string, format: date-time }
        resolved_at: { type: [string, 'null'], format: date-time }
        updated_at: { type: string, format: date-time }
        link: { type: string, format: uri }
    FindingPage:
      type: object
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Finding' } }
        next_cursor: { type: [string, 'null'] }
    Asset:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        type: { type: string }
        status: { type: [string, 'null'] }
        criticality: { type: [string, 'null'] }
        hostname: { type: [string, 'null'] }
        domain: { type: [string, 'null'] }
        os: { type: [object, 'null'] }
        risk_score: { type: [integer, 'null'] }
        owner_person_id: { type: [string, 'null'], format: uuid }
        updated_at: { type: string, format: date-time }
    AssetPage:
      type: object
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Asset' } }
        next_cursor: { type: [string, 'null'] }
    GenericPage:
      type: object
      properties:
        data: { type: array, items: { type: object } }
        next_cursor: { type: [string, 'null'] }
    Event:
      type: object
      description: The webhook body.
      properties:
        type: { type: string }
        id: { type: string, description: '`evt_` + uuid' }
        timestamp: { type: string, format: date-time }
        schema_version: { type: string }
        org: { type: object, properties: { id: { type: string, format: uuid } } }
        data: { type: object, description: OCSF 1.3.0 finding for finding events; a documented shape otherwise. }
    EventPage:
      type: object
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Event' } }
        next_cursor: { type: [string, 'null'] }
