Partner Integration Contract

KAIOS Partner Integration

Everything an integrator at an industrial robotics operator needs to ship one signed envelope into the live KAIOS fleet. Bearer-authenticated ingest, plaintext JSON, persisted to kaios_telemetry and reflected on the /kaios live status panel within one render.

Need the shortest verification path? Start the KAIOS verification quickstart →

Signed Receipt

Signed-receipt verification

An issuer signs the exact payload_string bytes and sends the envelope to the verifier. The signed claims are portable; the issuer's raw source records and signing key stay private.

receipt-envelope.json

{
  "signature": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "payload_string": "{\"ciphertext_bundle\":\"opaque:issuer-private-envelope-v1\",\"disclosed_fields\":{\"loan_size_usd\":75000,\"task\":\"undercollateralized-lending\"},\"issued_at\":\"2026-07-24T12:00:00Z\",\"issuer\":\"kaios.automa8.ai\"}",
  "payload": {
    "issuer": "kaios.automa8.ai",
    "issued_at": "2026-07-24T12:00:00Z",
    "disclosed_fields": {
      "task": "undercollateralized-lending",
      "loan_size_usd": 75000
    },
    "ciphertext_bundle": "opaque:issuer-private-envelope-v1"
  }
}

The signature above is an illustrative issuer-generated placeholder, not a production credential. The payload_string is compact canonical JSON: object keys are recursively sorted alphabetically, including the nested disclosed_fields object, before the issuer signs its UTF-8 bytes.

01 · Select claims

The issuer chooses the claims to disclose and places them in disclosed_fields.

02 · Canonicalize

It recursively sorts object keys and emits compact JSON as the exact payload_string.

03 · Sign bytes

The issuer signs the UTF-8 bytes of that string with Ed25519 using its private key.

04 · Verify claims

The verifier checks those bytes against KAIOS_ISSUER_PUBLIC_KEY, then returns valid, issuer metadata, and disclosed_fields.

Issuer boundary
The issuer retains raw/private source data and the Ed25519 signing private key. It decides which claims become signed and disclosed.

Verifier boundary
The verifier receives signed claims and any opaque ciphertext_bundle; it does not decrypt or persist that bundle. A valid signature authenticates issuer-signed claims, not a separate business-trust decision.

References

GET /api/kaios/verify · Full verification reference · Quickstart · FHE Workflow

Endpoint

POST `/api/kaios/ingest`

Plaintext JSON. One envelope per agent, per submission. Persisted to the kaios_telemetry table and overlaid on the live agent panel.

Method

POST

URL

https://automa-labs-ai.polsia.app/api/kaios/ingest

Base

https://automa-labs-ai.polsia.app

Content-Type

application/json

Schema

kai-ingest-1

Discovery

GET https://automa-labs-ai.polsia.app/api/kaios/ingest

Authentication

Bearer token in the Authorization header

Every request must present a partner-issued Bearer token. The token is per-partner and is supplied server-side via the KAIOS_INGEST_TOKEN environment variable. When that env var is unset on the server, the endpoint returns 503 with {"ok": false, "error": "Ingestion disabled"}. When set, any request with a missing, malformed, or mismatched token returns 401.

Authorization header

Authorization: Bearer <KAIOS_INGEST_TOKEN>

The example below is the illustrative value documented in the live contract — not a real token. Partners receive their own token out-of-band.

            Authorization: Bearer 5a3…c2e
          

Request Schema

Required fields

All four fields are required. Any missing or invalid field produces a 400 with the offending fields listed in errors.

Field	Type	Description
agent_id	string	Stable unique identifier for the deploying agent (e.g. "agent-7c3a").
status_code	integer	Partner-side numeric health/status code (0 = healthy).
uptime_seconds	integer	Partner-reported uptime since last restart, in seconds (>= 0).
last_seen_at	string	ISO-8601 timestamp of the agent reading.

Example Envelope

JSON body the partner posts

The values below come straight from the live contract — what the integrator sends and what the server stores.

json

{
  "agent_id": "agent-7c3a",
  "status_code": 0,
  "uptime_seconds": 43200,
  "last_seen_at": "2026-07-24T12:00:00Z"
}

Copy-paste

curl invocation

One command — sends the example envelope above to the live ingest endpoint with a Bearer token. The host is whatever the request landed on; the path is the same everywhere.

bash — curl

curl -X POST https://automa-labs-ai.polsia.app/api/kaios/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <KAIOS_INGEST_TOKEN>" \
  -d '{
  "agent_id": "agent-7c3a",
  "status_code": 0,
  "uptime_seconds": 43200,
  "last_seen_at": "2026-07-24T12:00:00Z"
}'

Replace <KAIOS_INGEST_TOKEN> with the token your KAIOS partner liaison gave you. The example body values map 1:1 to the request-schema table above — change agent_id to your deploying agent's stable identifier.

Response Codes

What the server can give back

Every terminal status the integrator needs to handle.

Status	Body	When
202	`{"ok":true,"accepted_at":"ISO-8601 string","replay_id":"string","id":"integer"}`	Envelope accepted and persisted to kaios_telemetry.
400	`{"ok":false,"errors":["string"]}`	Validation error — one or more required fields are missing or wrong type.
401	`{"ok":false,"error":"Unauthorized"}`	Authorization header missing, malformed, or token did not match.
503	`{"ok":false,"error":"Ingestion disabled: KAIOS_INGEST_TOKEN not configured"}`	Server-side ingestion disabled: KAIOS_INGEST_TOKEN env var is not set.

Persistence

What happens to a successful envelope

Every accepted envelope is written to the kaios_telemetry table and overlaid on the live status panel at /kaios on the next render. The same contract — including the example envelope and the response shapes — is published as plain JSON at https://automa-labs-ai.polsia.app/api/kaios/ingest, so a partner agent can pull the spec straight off the live endpoint rather than caching this page.