LogBrew Ingestion API

openapi: 3.2.0
info:
  contact:
    email: support@logbrew.co
    name: LogBrew support
    url: https://logbrew.co
  description: 'Send `Authorization: Bearer ` with an account access token or a project key. `logbrew login` signs in and stores an access token; `logbrew projects keys create` makes project keys. A read key reads one project''s telemetry and nothing else. Without the CLI, get an access token with device sign-in (RFC 8628): `POST /api/auth/device` with a form-encoded `client_id`, show the person the `user_code` and `verification_uri`, then poll `POST /api/auth/device/token` until they approve.


    Every error has the same JSON shape: a stable `code`, a readable `error`, and a `next` step that says how to recover. A `429` response carries `Retry-After`.


    Some operations have several response versions. This document describes the newest one, so send the `response_version` it requires. List operations return pages with `pagination=cursor`. Older versions keep their exact shape for clients that already use them.


    To test an integration without touching production data, create a separate project for it: each project has its own keys and data, and the free plan covers it. `load_sample_data` fills a new project with a connected example issue, logs, and trace that never count toward usage, `remove_sample_data` removes exactly those rows, and `send_test_event` checks a key end to end.'
  summary: Read and manage LogBrew projects, issues, logs, traces, actions, metrics, releases, and product analytics.
  title: LogBrew Ingestion API
  version: '1'
servers:
- description: LogBrew API
  url: https://api.logbrew.co
tags:
- description: Send telemetry from your own code when no LogBrew SDK fits.
  name: Ingestion
paths:
  /api/telemetry/ingest:
    post:
      description: Send logs, issues, spans, actions, and metrics for one project. Items with an id that was already accepted are acknowledged and not stored again. Accepts an account access token or a project key that sends telemetry (`sdk`, `server`, `browser`, or `cli`).
      operationId: send_telemetry
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NativeTelemetryEnvelope'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                actions: 1
                already_accepted: 1
                issues: 1
                logs: 1
                next: string
                next_action:
                  code: review_ingested_telemetry
                  target: telemetry_reads
                trace_spans: 1
              schema:
                $ref: '#/components/schemas/NativeTelemetryIngestResponse'
          description: Success.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/Error'
      security:
      - accessToken: []
      - projectKey:
        - sdk
        - server
        - browser
        - cli
      summary: Send logs, issues, spans, actions, and metrics for one project.
      tags:
      - Ingestion
  /v1/events:
    post:
      description: Send a batch of events in the format the LogBrew SDKs use. Needs a project key that sends telemetry (`sdk`, `server`, `browser`, or `cli`).
      operationId: send_sdk_events
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SdkEventBatch'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                actions: 1
                already_accepted: 1
                context_updated: false
                issues: 1
                logs: 1
                metrics: 1
                next: string
                next_action:
                  code: review_ingested_telemetry
                  target: telemetry_reads
                trace_spans: 1
              schema:
                $ref: '#/components/schemas/SdkEventIngestResponse'
          description: Success.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/Error'
      security:
      - projectKey:
        - sdk
        - server
        - browser
        - cli
      summary: Send a batch of events in the format the LogBrew SDKs use
      tags:
      - Ingestion
components:
  schemas:
    NativeTelemetryIngestResponse:
      description: Accepted ingestion counts grouped by telemetry stream.
      properties:
        actions:
          description: Number of accepted action items.
          format: uint
          minimum: 0
          type: integer
        already_accepted:
          default: 0
          description: Number of items whose client event ID was accepted earlier; they are not stored again.
          format: uint
          minimum: 0
          type: integer
        issues:
          description: Number of accepted issue items.
          format: uint
          minimum: 0
          type: integer
        logs:
          description: Number of accepted log items.
          format: uint
          minimum: 0
          type: integer
        next:
          description: Display-safe next step after accepting telemetry.
          type: string
        next_action:
          $ref: '#/components/schemas/NativeTelemetryIngestNextActionResponse'
          description: Stable machine-readable action for clients that should not parse `next`.
        trace_spans:
          description: Number of accepted trace span items.
          format: uint
          minimum: 0
          type: integer
      required:
      - issues
      - logs
      - trace_spans
      - actions
      - already_accepted
      - next
      - next_action
      type: object
    SdkEventIngestResponse:
      description: Accepted public SDK compatibility-ingest counts.
      properties:
        actions:
          description: Number of accepted product actions.
          format: uint
          minimum: 0
          type: integer
        already_accepted:
          default: 0
          description: Number of events whose ID was accepted earlier; they are not stored or billed again.
          format: uint
          minimum: 0
          type: integer
        context_updated:
          description: Whether this batch persisted release or environment marker context.
          type: boolean
        issues:
          description: Number of accepted issue events.
          format: uint
          minimum: 0
          type: integer
        logs:
          description: Number of accepted log events.
          format: uint
          minimum: 0
          type: integer
        metrics:
          description: Number of accepted metric events.
          format: uint
          minimum: 0
          type: integer
        next:
          description: Display-safe next step after successful ingestion.
          type: string
        next_action:
          $ref: '#/components/schemas/NativeTelemetryIngestNextActionResponse'
          description: Stable machine-readable review action shared with native ingestion.
        trace_spans:
          description: Number of accepted trace spans.
          format: uint
          minimum: 0
          type: integer
      required:
      - issues
      - logs
      - trace_spans
      - actions
      - metrics
      - already_accepted
      - context_updated
      - next
      - next_action
      type: object
    NativeIssueEvent:
      description: Error or crash candidate emitted by a native SDK.
      properties:
        attributes:
          description: Additional structured context.
        exception_type:
          description: Runtime exception or error type, if available.
          type:
          - string
          - 'null'
        fingerprint:
          description: SDK-provided grouping override.
          type:
          - string
          - 'null'
        id:
          description: Client event ID. A replay of an accepted ID is acknowledged, not stored again.
          type:
          - string
          - 'null'
        message:
          description: Human-readable failure message.
          type: string
        occurred_at:
          description: When the issue occurred in the client application.
          format: date-time
          type: string
        severity:
          description: 'User-facing severity: `info`, `warning`, `error`, or `critical`.


            SDK aliases such as `warn` and `fatal` are accepted at ingest and

            normalized by the backend before API responses.'
          type: string
        span_id:
          description: Exact span identifier for trace correlation, when available.
          type:
          - string
          - 'null'
        stack_frames:
          description: Structured stack frames used for stable grouping.
          items:
            $ref: '#/components/schemas/StackFrame'
          type: array
        stack_trace:
          description: Original stack trace text, if available.
          type:
          - string
          - 'null'
        title:
          description: Short title shown in issue lists.
          type: string
      required:
      - severity
      - title
      - message
      - stack_frames
      - attributes
      - occurred_at
      type: object
    SdkEventBatch:
      description: Event batch serialized by public `LogBrew` SDK transports.
      properties:
        client_report:
          anyOf:
          - $ref: '#/components/schemas/SdkClientReport'
          - type: 'null'
          description: Optional count of events the SDK dropped before sending them.
        events:
          description: Ordered SDK events.
          items:
            $ref: '#/components/schemas/SdkEvent'
          type: array
        sdk:
          $ref: '#/components/schemas/SdkEventIdentity'
          description: SDK identity shared by the batch.
      required:
      - sdk
      - events
      type: object
    NativeTelemetryIngestNextActionCode:
      description: Stable native telemetry ingest action codes for clients and agents.
      oneOf:
      - const: review_ingested_telemetry
        description: Review the telemetry that was just accepted.
        type: string
    SdkEventIdentity:
      description: Public SDK identity attached to one event batch.
      properties:
        language:
          description: Runtime language name.
          type: string
        name:
          description: SDK package or integration name.
          type: string
        version:
          description: SDK semantic version.
          type: string
      required:
      - name
      - language
      - version
      type: object
    NativeLogEvent:
      description: Structured log line emitted by a native SDK.
      properties:
        attributes:
          description: Additional structured fields.
        id:
          description: Client event ID. A replay of an accepted ID is acknowledged, not stored again.
          type:
          - string
          - 'null'
        level:
          description: 'SDK log level as emitted by the runtime.


            Accepted values include `trace`, `debug`, `info`, `warn`, `warning`,

            `error`, `fatal`, and `critical`. The backend stores and returns the

            canonical user-facing value.'
          type: string
        message:
          description: Log message.
          type: string
        occurred_at:
          description: When the log line occurred in the client application.
          format: date-time
          type: string
        source:
          description: Log source, usually `runtime`.
          type: string
        span_id:
          description: Exact span identifier for trace correlation, when available.
          type:
          - string
          - 'null'
      required:
      - level
      - message
      - source
      - attributes
      - occurred_at
      type: object
    NativeTelemetryEnvelope:
      description: A batch of native telemetry emitted by a first-party SDK.
      properties:
        environment:
          default: ''
          description: Deployment environment, such as `production` or `staging`.
          type: string
        items:
          description: Telemetry items carried by this envelope.
          items:
            $ref: '#/components/schemas/NativeTelemetryItem'
          type: array
        project_id:
          description: Target project that owns every item in this batch.
          format: uuid
          type: string
        release:
          description: Application release, build, or git SHA.
          type: string
        sdk_name:
          description: SDK name, such as `logbrew-rust` or `logbrew-swift`.
          type: string
        sdk_version:
          description: SDK semantic version.
          type: string
        service_name:
          description: Logical service name, such as `checkout-api`.
          type: string
        trace_id:
          description: Distributed trace ID shared by items in the envelope when available.
          type:
          - string
          - 'null'
      required:
      - project_id
      - release
      - service_name
      - sdk_name
      - sdk_version
      - items
      type: object
    NativeAction:
      description: Product action emitted by a native SDK.
      properties:
        distinct_id:
          description: Stable actor identifier.
          type: string
        id:
          description: Client event ID. A replay of an accepted ID is acknowledged, not stored again.
          type:
          - string
          - 'null'
        name:
          description: Machine-safe action name, such as `checkout_failed`.
          type: string
        occurred_at:
          description: When the action occurred.
          format: date-time
          type: string
        properties:
          description: Action properties.
        session_id:
          description: Client session identifier, if available.
          type:
          - string
          - 'null'
        span_id:
          description: Exact span identifier for trace correlation, when available.
          type:
          - string
          - 'null'
      required:
      - name
      - distinct_id
      - occurred_at
      - properties
      type: object
    NativeTelemetryItem:
      description: A single native telemetry item.
      oneOf:
      - description: Error or crash candidate that should be grouped into an issue.
        properties:
          data:
            $ref: '#/components/schemas/NativeIssueEvent'
          type:
            const: issue
            type: string
        required:
        - type
        - data
        type: object
      - description: Structured application log line.
        properties:
          data:
            $ref: '#/components/schemas/NativeLogEvent'
          type:
            const: log
            type: string
        required:
        - type
        - data
        type: object
      - description: Distributed trace span.
        properties:
          data:
            $ref: '#/components/schemas/NativeTraceSpanEvent'
          type:
            const: trace_span
            type: string
        required:
        - type
        - data
        type: object
      - description: Product action event.
        properties:
          data:
            $ref: '#/components/schemas/NativeAction'
          type:
            const: action
            type: string
        required:
        - type
        - data
        type: object
    SdkEvent:
      description: One event emitted by a public `LogBrew` SDK.
      properties:
        attributes:
          additionalProperties: true
          description: Validated event attributes emitted by the SDK.
          type: object
        id:
          description: Caller-provided stable event identifier.
          type: string
        timestamp:
          description: RFC 3339 event timestamp.
          format: date-time
          type: string
        type:
          description: Event category such as `issue`, `log`, `span`, or `action`.
          type: string
      required:
      - type
      - id
      - timestamp
      - attributes
      type: object
    NativeTraceSpanEvent:
      description: Distributed trace span emitted by a native SDK.
      properties:
        attributes:
          description: Additional span attributes.
        duration_ms:
          description: Span duration in milliseconds.
          format: int64
          type: integer
        id:
          description: Client event ID. A replay of an accepted ID is acknowledged, not stored again.
          type:
          - string
          - 'null'
        name:
          description: Human-readable span name.
          type: string
        operation:
          description: Operation category, such as `http.server` or `db.query`.
          type: string
        parent_span_id:
          description: Parent span ID, absent for root spans.
          type:
          - string
          - 'null'
        span_id:
          description: Span ID unique within the trace.
          type: string
        started_at:
          description: Span start timestamp.
          format: date-time
          type: string
        status:
          description: Span status, such as `ok`, `error`, or `cancelled`.
          type:
          - string
          - 'null'
        trace_id:
          description: W3C/OpenTelemetry-compatible trace ID.
          type: string
      required:
      - trace_id
      - span_id
      - name
      - operation
      - started_at
      - duration_ms
      - attributes
      type: object
    NativeTelemetryIngestNextActionTarget:
      description: Stable native telemetry ingest action targets for clients and agents.
      oneOf:
      - const: telemetry_reads
        description: Telemetry read routes, dashboard signal views, or live feed.
        type: string
    SdkClientReport:
      description: Events an SDK dropped locally since its previous acknowledged report.
      properties:
        dropped_events:
          additionalProperties:
            format: uint64
            minimum: 0
            type: integer
          default: {}
          description: 'Dropped event count by reason code, such as `queue_overflow`.


            At most 16 reasons matching `^[a-z][a-z0-9_]{0,63}$`, each counting

            1 to 1,000,000,000 events.'
          type: object
        report_id:
          description: 'Stable ID of these counts: 16 to 64 characters matching `^[A-Za-z0-9_-]+$`.


            Every resend of one report ID is counted once, even inside a different batch.'
          type:
          - string
          - 'null'
      type: object
    NativeTelemetryIngestNextActionResponse:
      description: Stable machine-readable next action for native telemetry ingest responses.
      properties:
        code:
          $ref: '#/components/schemas/NativeTelemetryIngestNextActionCode'
          description: Stable action code.
        target:
          $ref: '#/components/schemas/NativeTelemetryIngestNextActionTarget'
          description: Stable action target.
      required:
      - code
      - target
      type: object
    StackFrame:
      description: Structured stack frame for native issue grouping.
      properties:
        column:
          description: Source column number.
          format: int32
          type:
          - integer
          - 'null'
        debug_id:
          description: Release-artifact debug identity retained for hosted symbolication.
          format: uuid
          type:
          - string
          - 'null'
        filename:
          description: Source filename or path.
          type:
          - string
          - 'null'
        function:
          description: Function or method name.
          type:
          - string
          - 'null'
        in_app:
          description: Whether the SDK classified this frame as application-owned code.
          type:
          - boolean
          - 'null'
        line:
          description: Source line number.
          format: int32
          type:
          - integer
          - 'null'
        module:
          description: Module, package, namespace, or crate path.
          type:
          - string
          - 'null'
      type: object
  responses:
    Error:
      content:
        application/json:
          schema:
            properties:
              code:
                description: Stable reason, such as `unauthorized`, `forbidden`, `not_found`, `validation_failed`, `rate_limited`, or `usage_limit_exceeded`.
                type: string
              deleted_at:
                description: When the account was deleted, on `account_recovery_available`.
                type: string
              error:
                description: What went wrong, in words.
                type: string
              limit:
                description: The limit that was reached.
                type: string
              next:
                description: How to recover.
                type: string
              next_action:
                description: The recovery as stable codes.
                properties:
                  code:
                    description: Stable recovery action, such as `sign_in` or `retry_later`.
                    type: string
                  target:
                    description: Where the recovery happens, such as `auth` or `billing`.
                    type: string
                required:
                - code
                - target
                type: object
              recovery_token:
                description: Token for restore_account, on `account_recovery_available`.
                type: string
              reset_at:
                description: When the limit resets, as an RFC 3339 time.
                type: string
              retry_after_seconds:
                description: Seconds to wait, on `rate_limited`.
                minimum: 0
                type: integer
            required:
            - error
            - code
            - next
            - next_action
            type: object
      description: The request failed. `code` names the reason and `next` says how to recover.
    RateLimited:
      content:
        application/json:
          schema:
            properties:
              code:
                description: Stable reason, such as `unauthorized`, `forbidden`, `not_found`, `validation_failed`, `rate_limited`, or `usage_limit_exceeded`.
                type: string
              deleted_at:
                description: When the account was deleted, on `account_recovery_available`.
                type: string
              error:
                description: What went wrong, in words.
                type: string
              limit:
                description: The limit that was reached.
                type: string
              next:
                description: How to recover.
                type: string
              next_action:
                description: The recovery as stable codes.
                properties:
                  code:
                    description: Stable recovery action, such as `sign_in` or `retry_later`.
                    type: string
                  target:
                    description: Where the recovery happens, such as `auth` or `billing`.
                    type: string
                required:
                - code
                - target
                type: object
              recovery_token:
                description: Token for restore_account, on `account_recovery_available`.
                type: string
              reset_at:
                description: When the limit resets, as an RFC 3339 time.
                type: string
              retry_after_seconds:
                description: Seconds to wait, on `rate_limited`.
                minimum: 0
                type: integer
            required:
            - error
            - code
            - next
            - next_action
            type: object
      description: Too many requests. Wait the `Retry-After` seconds, then retry.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            minimum: 0
            type: integer
    Unauthorized:
      content:
        application/json:
          schema:
            properties:
              code:
                description: Stable reason, such as `unauthorized`, `forbidden`, `not_found`, `validation_failed`, `rate_limited`, or `usage_limit_exceeded`.
                type: string
              deleted_at:
                description: When the account was deleted, on `account_recovery_available`.
                type: string
              error:
                description: What went wrong, in words.
                type: string
              limit:
                description: The limit that was reached.
                type: string
              next:
                description: How to recover.
                type: string
              next_action:
                description: The recovery as stable codes.
                properties:
                  code:
                    description: Stable recovery action, such as `sign_in` or `retry_later`.
                    type: string
                  target:
                    description: Where the recovery happens, such as `auth` or `billing`.
                    type: string
                required:
                - code
                - target
                type: object
              recovery_token:
                description: Token for restore_account, on `account_recovery_available`.
                type: string
              reset_at:
                description: When the limit resets, as an RFC 3339 time.
                type: string
              retry_after_seconds:
                description: Seconds to wait, on `rate_limited`.
                minimum: 0
                type: integer
            required:
            - error
            - code
            - next
            - next_action
            type: object
      description: The credential is missing, expired, or revoked, or this operation does not accept it.
  securitySchemes:
    accessToken:
      bearerFormat: JWT
      description: Account access token. It acts as your account in every project you can reach. `logbrew login` creates one; renew it with refresh_access_token before it expires.
      scheme: bearer
      type: http
    projectKey:
      description: 'Project key. A key reaches only its own project and has one kind: `read` keys (prefix `lbw_read_`) read telemetry; `sdk`, `server`, `browser`, and `cli` keys (prefix `lbw_ingest_`) send telemetry; `artifact` keys upload debug files. Each operation''s security requirement lists the kinds it accepts.'
      scheme: bearer
      type: http