Jentic Events API

openapi: 3.2.0
info:
  contact:
    email: support@jentic.com
    name: Jentic Platform Team
    url: https://jentic.com/
  description: '## Overview ##

    The **Jentic Control Plane API** is the unified HTTP surface of the

    Jentic platform''s control plane — every administrative and

    metadata-facing endpoint outside the Broker data plane. The control plane is the administrative counterpart to the

    Broker data plane: where the Broker executes

    upstream API calls on behalf of agents, the control plane is where

    humans, operators, and agents configure *what* the Broker is

    allowed to do, *for whom*, *with which credentials*, *against

    which registered APIs*, and *with what telemetry retained*. ## Components ##

    High-level components for the control plane API. - **Core / Access** — credentials, toolkits,

    and PBAC grants and runtime params. Owns *who can call what, with which secret*. - **Registry** — registered APIs, immutable

    revisions, operations, search, lookup. Owns *what APIs are

    registered for this deployment and what they look like at any

    given revision*. - **Admin / Audit** — users, permissions,

    execution telemetry, async-job tracker, and dashboard event

    stream. Owns *who can sign in with what permissions* together

    with *what actually happened* — the human roster, the

    append-only records of brokered executions, the unified

    `Job` resource that both Registry imports and Broker

    async-execution calls feed into, and a curated `/events`

    surface for dashboards and operators. ## Authentication ##


    Today the platform ships a local username + password identity

    provider for human users, alongside agent identity (Dynamic Client

    Registration + RFC 7523 JWT-bearer assertions) and service-account

    client credentials — every authenticated operation expects

    `Authorization: Bearer ` (`BearerAuth`, an opaque `at_`

    token) except `GET /health`, `POST /auth/login`,

    `POST /users:create-admin`, and `POST /users:redeem-invite`. Human tokens are issued by `POST /auth/login` with a fixed 1-hour

    TTL and can be re-minted before expiry via `POST /auth/refresh`

    (sliding session, bounded by an absolute window —

    `admin.auth.session_ttl_seconds`, 12 hours by default); agents and

    service accounts obtain tokens from `POST /oauth/token` (see

    `BearerAuth`). The `permissions` claim on a token is a snapshot at

    issue time; permission changes take effect at the next re-issue —

    the next refresh or re-login (≤ 1 hour with the default TTL). The platform ships **no default credentials**. On a fresh

    install the users table is empty, so `GET /health` returns

    `setup_required: true` with `next_step: create_admin`. The

    operator creates the first administrator with `POST

    /users:create-admin {email, password}` — a one-time,

    unauthenticated, self-closing endpoint: it succeeds only while

    the users table is empty and returns `410 setup_already_complete`

    once any user exists (a single-row setup sentinel is the

    concurrency backstop, so two racing callers — even with different

    emails — cannot both bootstrap). It grants `org:admin`, sets the operator''s chosen

    password (so `must_change_password` is **false** — no forced

    rotation), and returns a ready-to-use `LoginResponse`

    (auto-login). After the first user exists `setup_required` flips

    to `false`. See the **Users** tag for the full onboarding

    walkthrough. External SSO providers (Okta, AWS Cognito, Auth0, Azure AD)

    plug in via the `User.auth_provider: external` hook plus an

    `external_subject_id` mapping; no concrete provider ships in

    this revision. Agent identity (separate from human users) uses

    Dynamic Client Registration (`POST /register`) with the agent''s

    JWKS, then RFC 7523 JWT-bearer assertions exchanged at

    `POST /oauth/token` for an opaque access token. ## Cross-cutting conventions


    - Every API reference uses the loose

    `APIReference(vendor, name, version)` data structure. There is no

    foreign key between Core, Registry, and Admin / Audit — the

    tuple is the only join. - **Error shape.** Every error response is RFC 9457 Problem

    Details (`application/problem+json`) using the shared

    `ProblemDetails` schema from

    jentic/api-problem-details.'
  license:
    identifier: Apache-2.0
    name: Apache-2.0
  summary: HTTP surface of the Jentic platform's control plane — Core / Access (credentials, toolkits), Registry (registered APIs, operations, search), and Admin / Audit (execution telemetry, async jobs).
  title: Jentic Control Plane Events API
  version: 0.39.0
servers:
- description: Same-origin (relative)
  url: /
security:
- BearerAuth: []
tags:
- description: Curated, severity-tagged event stream surfaced to dashboards and operators. Each event is either **informational** (no action required, e.g. `import.completed`) or **actionable** (requires operator follow-up, e.g. `credential.expiring_soon`, `execution.repeated_failure`). Events reference the underlying `ExecutionRecord` or `Job` via `_links` and share `trace_id` for correlation. Subscribe live via `GET /events/stream` (Server-Sent Events) or poll `GET /events` with a `since=` filter.
  name: Events
paths:
  /events:
    get:
      description: List events with optional filters.
      operationId: listEvents
      parameters:
      - in: query
        name: event_type
        required: false
        schema:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Event Type
      - in: query
        name: severity
        required: false
        schema:
          anyOf:
          - items:
              $ref: '#/components/schemas/EventSeverity'
            type: array
          - type: 'null'
          title: Severity
      - in: query
        name: requires_action
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Requires Action
      - in: query
        name: acknowledged
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Acknowledged
      - in: query
        name: from
        required: false
        schema:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: From
      - in: query
        name: to
        required: false
        schema:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: To
      - in: query
        name: trace_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Trace Id
      - in: query
        name: actor_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Actor Id
      - in: query
        name: actor_type
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Actor Type
      - in: query
        name: cursor
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - in: query
        name: limit
        required: false
        schema:
          default: 25
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListResponse'
          description: Successful Response
        '400':
          content:
            application/problem+json:
              example:
                detail: The request was malformed or failed a precondition.
                instance: /example/path
                status: 400
                title: Bad Request
                type: bad_request
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Bad Request
        '401':
          content:
            application/problem+json:
              example:
                detail: Authentication is required or the bearer token is invalid.
                instance: /example/path
                status: 401
                title: Unauthorized
                type: unauthorized
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              example:
                detail: The authenticated principal lacks the required permission.
                instance: /example/path
                status: 403
                title: Forbidden
                type: forbidden
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Forbidden
        '422':
          content:
            application/problem+json:
              example:
                detail: Request validation failed; see errors[] for details.
                errors:
                - detail: Field 'name' must not be blank.
                  pointer: '#/name'
                instance: /example/path
                status: 422
                title: Unprocessable Entity
                type: validation_error
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              example:
                detail: An unexpected error occurred.
                instance: /example/path
                status: 500
                title: Internal Server Error
                type: server_error
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Internal Server Error
        '503':
          content:
            application/problem+json:
              example:
                detail: The database is temporarily unavailable; please retry.
                instance: /example/path
                status: 503
                title: Service Unavailable
                type: database_unavailable
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Service Unavailable
      security:
      - BearerAuth: []
      summary: List Events
      tags:
      - Events
  /events/stream:
    get:
      description: Stream events as Server-Sent Events.
      operationId: streamEvents
      parameters:
      - in: query
        name: since
        required: false
        schema:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Since
      - in: query
        name: event_type
        required: false
        schema:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Event Type
      - in: query
        name: severity
        required: false
        schema:
          anyOf:
          - items:
              $ref: '#/components/schemas/EventSeverity'
            type: array
          - type: 'null'
          title: Severity
      - in: query
        name: requires_action
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Requires Action
      - in: query
        name: trace_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Trace Id
      - in: query
        name: actor_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Actor Id
      - in: query
        name: actor_type
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Actor Type
      - in: header
        name: Last-Event-ID
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Last-Event-Id
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '400':
          content:
            application/problem+json:
              example:
                detail: The request was malformed or failed a precondition.
                instance: /example/path
                status: 400
                title: Bad Request
                type: bad_request
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Bad Request
        '401':
          content:
            application/problem+json:
              example:
                detail: Authentication is required or the bearer token is invalid.
                instance: /example/path
                status: 401
                title: Unauthorized
                type: unauthorized
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              example:
                detail: The authenticated principal lacks the required permission.
                instance: /example/path
                status: 403
                title: Forbidden
                type: forbidden
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Forbidden
        '422':
          content:
            application/problem+json:
              example:
                detail: Request validation failed; see errors[] for details.
                errors:
                - detail: Field 'name' must not be blank.
                  pointer: '#/name'
                instance: /example/path
                status: 422
                title: Unprocessable Entity
                type: validation_error
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              example:
                detail: An unexpected error occurred.
                instance: /example/path
                status: 500
                title: Internal Server Error
                type: server_error
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Internal Server Error
        '503':
          content:
            application/problem+json:
              example:
                detail: The database is temporarily unavailable; please retry.
                instance: /example/path
                status: 503
                title: Service Unavailable
                type: database_unavailable
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Service Unavailable
      security:
      - BearerAuth: []
      summary: Stream Events
      tags:
      - Events
  /events/{event_id}:
    get:
      description: Get an event by ID.
      operationId: getEvent
      parameters:
      - in: path
        name: event_id
        required: true
        schema:
          title: Event Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
          description: Successful Response
        '400':
          content:
            application/problem+json:
              example:
                detail: The request was malformed or failed a precondition.
                instance: /example/path
                status: 400
                title: Bad Request
                type: bad_request
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Bad Request
        '401':
          content:
            application/problem+json:
              example:
                detail: Authentication is required or the bearer token is invalid.
                instance: /example/path
                status: 401
                title: Unauthorized
                type: unauthorized
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              example:
                detail: The authenticated principal lacks the required permission.
                instance: /example/path
                status: 403
                title: Forbidden
                type: forbidden
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Forbidden
        '422':
          content:
            application/problem+json:
              example:
                detail: Request validation failed; see errors[] for details.
                errors:
                - detail: Field 'name' must not be blank.
                  pointer: '#/name'
                instance: /example/path
                status: 422
                title: Unprocessable Entity
                type: validation_error
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              example:
                detail: An unexpected error occurred.
                instance: /example/path
                status: 500
                title: Internal Server Error
                type: server_error
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Internal Server Error
        '503':
          content:
            application/problem+json:
              example:
                detail: The database is temporarily unavailable; please retry.
                instance: /example/path
                status: 503
                title: Service Unavailable
                type: database_unavailable
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Service Unavailable
      security:
      - BearerAuth: []
      summary: Get Event
      tags:
      - Events
    patch:
      description: Acknowledge an event.
      operationId: acknowledgeEvent
      parameters:
      - in: path
        name: event_id
        required: true
        schema:
          title: Event Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventAcknowledgeRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
          description: Successful Response
        '400':
          content:
            application/problem+json:
              example:
                detail: The request was malformed or failed a precondition.
                instance: /example/path
                status: 400
                title: Bad Request
                type: bad_request
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Bad Request
        '401':
          content:
            application/problem+json:
              example:
                detail: Authentication is required or the bearer token is invalid.
                instance: /example/path
                status: 401
                title: Unauthorized
                type: unauthorized
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              example:
                detail: The authenticated principal lacks the required permission.
                instance: /example/path
                status: 403
                title: Forbidden
                type: forbidden
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Forbidden
        '422':
          content:
            application/problem+json:
              example:
                detail: Request validation failed; see errors[] for details.
                errors:
                - detail: Field 'name' must not be blank.
                  pointer: '#/name'
                instance: /example/path
                status: 422
                title: Unprocessable Entity
                type: validation_error
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              example:
                detail: An unexpected error occurred.
                instance: /example/path
                status: 500
                title: Internal Server Error
                type: server_error
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Internal Server Error
        '503':
          content:
            application/problem+json:
              example:
                detail: The database is temporarily unavailable; please retry.
                instance: /example/path
                status: 503
                title: Service Unavailable
                type: database_unavailable
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Service Unavailable
      security:
      - BearerAuth: []
      summary: Acknowledge Event
      tags:
      - Events
components:
  schemas:
    ProblemDetail:
      description: 'RFC 9457 Problem Details for HTTP APIs.


        This is the standard error response format for all Jentic APIs.

        Content-Type: application/problem+json


        See: https://www.rfc-editor.org/rfc/rfc9457.html'
      examples:
      - detail: The request body is missing one or more required fields.
        errors:
        - detail: Field 'name' is required.
          pointer: '#/name'
        instance: /v2/capability-sets
        status: 400
        title: Bad Request
        type: about:blank
      properties:
        code:
          anyOf:
          - maxLength: 50
            type: string
          - type: 'null'
          description: An optional provider-specific code for internal error taxonomy and observability correlation.
          examples:
          - JENTIC-4001
          title: Code
        detail:
          description: A human-readable explanation specific to this occurrence of the problem. MUST be present. Provide actionable information where possible.
          examples:
          - The request body is missing required field 'name'.
          maxLength: 4096
          title: Detail
          type: string
        errors:
          anyOf:
          - items:
              $ref: '#/components/schemas/ErrorItem'
            maxItems: 1000
            type: array
          - type: 'null'
          description: An array of granular error details. Use when multiple validation errors or field-level problems need to be surfaced in a single response.
          title: Errors
        instance:
          anyOf:
          - maxLength: 1024
            type: string
          - type: 'null'
          description: A URI reference identifying the specific occurrence of the problem. Typically the request path.
          examples:
          - /v2/capability-sets
          title: Instance
        status:
          anyOf:
          - maximum: 599.0
            minimum: 100.0
            type: integer
          - type: 'null'
          description: The HTTP status code for this occurrence of the problem.
          examples:
          - 400
          title: Status
        title:
          anyOf:
          - maxLength: 1024
            type: string
          - type: 'null'
          description: A short, human-readable summary of the problem type. Should not change between occurrences except for localisation purposes.
          examples:
          - Bad Request
          title: Title
        type:
          default: about:blank
          description: A URI reference identifying the problem type. When set to 'about:blank', the title SHOULD be the standard HTTP status phrase. Use an IANA-registered type URI where one applies.
          examples:
          - about:blank
          maxLength: 1024
          title: Type
          type: string
      required:
      - detail
      title: ProblemDetail
      type: object
    EventListResponse:
      description: Paginated list of events.
      properties:
        data:
          items:
            $ref: '#/components/schemas/EventResponse'
          title: Data
          type: array
        has_more:
          title: Has More
          type: boolean
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      required:
      - data
      - has_more
      title: EventListResponse
      type: object
    EventResponse:
      description: Event representation in API responses.
      properties:
        _links:
          $ref: '#/components/schemas/EventLinks'
        acknowledged:
          title: Acknowledged
          type: boolean
        acknowledged_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Acknowledged At
        acknowledged_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Acknowledged By
        actor_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Actor Id
        actor_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Actor Type
        created_at:
          format: date-time
          title: Created At
          type: string
        data:
          additionalProperties: true
          title: Data
          type: object
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
        event_id:
          title: Event Id
          type: string
        requires_action:
          title: Requires Action
          type: boolean
        severity:
          $ref: '#/components/schemas/EventSeverity'
        summary:
          title: Summary
          type: string
        trace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trace Id
        type:
          title: Type
          type: string
      required:
      - event_id
      - type
      - severity
      - summary
      - requires_action
      - acknowledged
      - created_at
      - _links
      title: EventResponse
      type: object
    EventSeverity:
      description: Severity level for platform events.
      enum:
      - info
      - warning
      - error
      - critical
      title: EventSeverity
      type: string
    ErrorItem:
      description: 'A granular error detail entry within the errors[] array of a ProblemDetails response.


        At least one of pointer, parameter, or header SHOULD be present to identify the error source.'
      properties:
        code:
          anyOf:
          - maxLength: 50
            type: string
          - type: 'null'
          description: An optional provider-specific code identifying this error in internal taxonomy or documentation.
          examples:
          - JENTIC-V-001
          title: Code
        detail:
          description: A human-readable explanation of this specific error. Be precise — name the field, parameter, or header involved.
          examples:
          - Field 'name' must not be blank.
          maxLength: 4096
          title: Detail
          type: string
        header:
          anyOf:
          - maxLength: 1024
            type: string
          - type: 'null'
          description: The name of the request header that is the source of this error.
          examples:
          - Authorization
          title: Header
        parameter:
          anyOf:
          - maxLength: 1024
            type: string
          - type: 'null'
          description: The name of the query or path parameter that is the source of this error.
          examples:
          - limit
          title: Parameter
        pointer:
          anyOf:
          - maxLength: 1024
            type: string
          - type: 'null'
          description: A JSON Pointer (RFC 6901) to the specific request body property that is the source of this error.
          examples:
          - '#/name'
          title: Pointer
      required:
      - detail
      title: ErrorItem
      type: object
    EventLinks:
      description: HAL-style links for an event.
      properties:
        action:
          anyOf:
          - type: string
          - type: 'null'
          title: Action
        execution:
          anyOf:
          - type: string
          - type: 'null'
          title: Execution
        job:
          anyOf:
          - type: string
          - type: 'null'
          title: Job
        self:
          title: Self
          type: string
      required:
      - self
      title: EventLinks
      type: object
    EventAcknowledgeRequest:
      description: Request body for acknowledging an event.
      properties:
        acknowledged:
          title: Acknowledged
          type: boolean
        note:
          anyOf:
          - maxLength: 2000
            type: string
          - type: 'null'
          title: Note
      required:
      - acknowledged
      title: EventAcknowledgeRequest
      type: object
  securitySchemes:
    BearerAuth:
      description: 'Opaque bearer access token (prefixed `at_`), sent as `Authorization: Bearer <token>`. It is **not** a JWT — it is a random string validated server-side by lookup, so it cannot be decoded by the client.


        Obtain one from `POST /oauth/token` using the grant for your actor type:

        - **Agents** — `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer` with a JWT assertion signed by the key registered via `POST /register` (the JWT is the *assertion*, not the resulting access token).

        - **Service accounts** — `grant_type=client_credentials` with `client_id` + `client_secret`.

        - **Users** — `grant_type=authorization_code` (interactive) or `grant_type=password`; refresh either with `grant_type=refresh_token`.


        Service accounts can also mint short-lived, scope-narrowed task tokens for agents via `POST /oauth/mint`.


        Per-endpoint scope and actor-type requirements are not modelled in this document (OpenAPI cannot faithfully express the OR-of-scopes / `org:admin` bypass / service-layer enforcement); see `GET /reference/endpoints.json` for the authoritative authorization reference.'
      scheme: bearer
      type: http
x-tagGroups:
- name: Core / Access
  tags:
  - Credentials
  - Toolkits
  - Toolkit Keys
  - Toolkit Credentials
  - Toolkit Permissions
  - Access Requests
- name: Registry
  tags:
  - APIs
  - API Operations
  - API Spec
  - Catalog
  - Search
  - Inspect
  - Lookup
  - Notes
  - Overlays
- name: Admin / Audit
  tags:
  - Users
  - Actors
  - Permissions
  - Executions
  - Jobs
  - Events
  - Audit
  - Monitoring
  - Configuration
  - OAuth Clients
- name: Platform Actors
  tags:
  - Identity
  - Agents
  - Service Accounts
  - OAuth
  - Agent Registration
  - Discovery
- name: Operations
  tags:
  - System
  - MCP