Jentic Notes 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 Notes API
  version: 0.39.0
servers:
- description: Same-origin (relative)
  url: /
security:
- BearerAuth: []
tags:


# --- truncated at 32 KB (33 KB total) ---
# Full source: https://artifacts.apis.io/jentic/openapi/jentic-notes-api-openapi.yml