Reference

API Reference

REST API endpoints for integrating Hikigai agents into your frontend applications.

Base URL: https://backend.hikigaiplatform.io

Authentication

Authenticate using an API key to receive a JWT token for all subsequent requests.

POST/api/v1/auth/exchange

Exchange your API key for a JWT access token.

Request Headers

X-API-Key: hikigai_your_api_key_here

cURL Example

curl --location --request POST 'https://backend.hikigaiplatform.io/api/v1/auth/exchange' \
  --header 'X-API-Key: your_api_key_here'

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "scopes": ["deploy", "invoke", "read", "manage"],
  "project_id": "project-id-here"
}

Token lifetime: JWT tokens expire in 24 hours. Store the token securely and exchange a new one when it expires.

Agent Deployment

POST/api/v1/agents/deploy

Deploy a new agent with optional MCP connector support.

Request Headers

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
X-Project-ID: YOUR_PROJECT_ID

Request Body

{
  "name": "{agent-slug}",
  "display_name": "Agent Display Name",
  "version": "1.0.0",
  "description": "Agent description",
  "agent_type": "llm",
  "model": "gemini-2.0-flash",
  "instruction": "System Role: You are a helpful assistant...",
  "input_schema": {
    "fields": {
      "message": { "type": "string", "required": true }
    }
  },
  "output_schema": {
    "fields": {
      "result": { "type": "string" }
    }
  },
  "mcp_connectors": [
    {
      "slug": "connector-slug",
      "tool_filter": ["*"],
      "required": true
    }
  ]
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/agents/deploy' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --data '{
    "name": "{agent-slug}",
    "display_name": "Agent Display Name",
    "version": "1.0.0",
    "description": "Agent description",
    "agent_type": "llm",
    "model": "gemini-2.0-flash",
    "instruction": "System Role: You are a helpful assistant..."
  }'

Response

{
  "id": "ag_abc123def456",
  "name": "cpt2-code-agent-v2",
  "slug": "cpt2-code-agent-v2",
  "status": "deployed",
  "mcp_connectors": [
    {
      "slug": "google-health-connect",
      "tool_filter": ["*"],
      "required": true
    }
  ]
}

Agent Invocation

Request timeout (optional)

The timeout field is not required. Existing integrations keep working without any changes — if you omit it, the platform uses the agent's deploy-time timeout (typically 60 seconds).

Deploying agents is unchanged: you do not need to set timeout at deploy time unless you want a different default for that agent. At invoke time, passtimeoutonly when you need a longer or shorter limit for a specific call (5–300 seconds).

There are two independent timeouts to be aware of:

Request body ("timeout": 300) — how long the Hikigai platform waits for the agent to finish processing.
HTTP client (e.g. requests.post(..., timeout=300)) — how long your application waits for the API response. Set this to match or exceed the body timeout so your app does not give up before the server responds.

This matches SDK behavior: agent.invoke(..., timeout=300) is also optional and uses the same defaults when omitted.

POST/api/v1/agents/{agent_slug}/invoke

Invoke an agent to process a message with optional MCP connector data.

Request Headers

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
X-Project-ID: YOUR_PROJECT_ID

Request Body

{
  "input": {
    "query": "Show me my blood pressure data for today",
    "userId": "android-user-010",
    "deviceId": "056ac949aa621795"
  },
  "timeout": 300,
  "connectors": {
    "google-health-connect": {}
  }
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/agents/{agent-slug}/invoke' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --data '{
    "input": {
      "message": "Your message here"
    },
    "timeout": 300
  }'

Response

{
  "content": "Based on the health data, the patient shows stable vital signs...",
  "agent_id": "ag_abc123def456",
  "session_id": "session-123",
  "latency_ms": 1250,
  "tokens_used": 342,
  "request_id": "req_xyz789"
}

Streaming

POST/api/v1/agents/{agent_slug}/stream

Stream agent responses via Server-Sent Events (SSE). Useful for real-time UI updates.

Request Headers

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
Accept: text/event-stream
X-Project-ID: YOUR_PROJECT_ID

Request Body

{
  "input": {
    "query": "Your query here",
    "userId": "user-id",
    "deviceId": "device-id"
  },
  "timeout": 300,
  "connectors": {
    "connector-slug": {}
  },
  "session_id": "session-abc123"
}

timeout is optional for streaming as well — see the explanation above.

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/agents/{agent-slug}/stream' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: text/event-stream' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --data '{
    "input": {
      "query": "Your query here",
      "userId": "user-id",
      "deviceId": "device-id"
    },
    "connectors": {
      "connector-slug": {}
    }
  }' \
  --no-buffer

Response Format (SSE)

data: Based

data: on

data: the

data: health

data: data

data: [DONE]

SSE Format: Responses arrive as newline-delimited text chunks. Each chunk is prefixed with data: and followed by double newlines. The stream ends with data: [DONE].

Agent Management

GET/api/v1/agents

List all agents with pagination. Includes mcp_connectors configuration.

Request Headers

Authorization: Bearer YOUR_TOKEN
X-Project-ID: YOUR_PROJECT_ID

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20)

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/agents?page=1&per_page=20' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Project-ID: YOUR_PROJECT_ID'

Response

{
  "agents": [
    {
      "id": "ag_abc123",
      "name": "agent-name",
      "slug": "agent-slug",
      "description": "Agent description",
      "status": "active",
      "mcp_connectors": [
        {
          "slug": "connector-slug",
          "tool_filter": ["*"],
          "required": true
        }
      ]
    }
  ],
  "total": 5,
  "page": 1,
  "per_page": 20
}

GET/api/v1/agents/{agent_slug}

Get details of a specific agent, including mcp_connectors configuration.

Request Headers

Authorization: Bearer YOUR_TOKEN
X-Project-ID: YOUR_PROJECT_ID

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/agents/{agent-slug}' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Project-ID: YOUR_PROJECT_ID'

Response

{
  "id": "ag_abc123def456",
  "name": "agent-name",
  "slug": "agent-slug",
  "model": "gemini-2.0-flash",
  "instruction": "You are a helpful assistant...",
  "description": "Agent description",
  "status": "active",
  "mcp_connectors": [
    {
      "slug": "connector-slug",
      "tool_filter": ["*"],
      "required": true
    }
  ],
  "invocation_count": 1542
}

POST/api/v1/agents/{agent_slug}/redeploy

Redeploy an agent with updated configuration and mcp_connectors.

Request Headers

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
X-Project-ID: YOUR_PROJECT_ID

Request Body

{
  "instruction": "Updated system prompt",
  "model": "gemini-2.0-flash",
  "mcp_connectors": [
    {
      "slug": "connector-slug",
      "tool_filter": ["*"],
      "required": true
    }
  ]
}

cURL Example

curl --location --request POST 'https://backend.hikigaiplatform.io/api/v1/agents/{agent-slug}/redeploy' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --data '{
    "instruction": "Updated system prompt",
    "model": "gemini-2.0-flash",
    "mcp_connectors": [
      {
        "slug": "connector-slug",
        "tool_filter": ["*"],
        "required": true
      }
    ]
  }'

Response

{
  "id": "ag_abc123def456",
  "name": "agent-name",
  "slug": "agent-slug",
  "status": "deployed",
  "mcp_connectors": [
    {
      "slug": "connector-slug",
      "tool_filter": ["*"],
      "required": true
    }
  ]
}

End-User Identity

Give your app's end users — clinicians, patients, staff — their own signup, login, multi-factor auth, QR badge login, and single sign-on. Each app gets a dedicated AWS Cognito user pool that the platform provisions and runs for you, so you never touch AWS. Login returns standard OIDC tokens (ID, access, refresh).

Two ways to host users. managed keeps users in Hikigai's Cognito (zero setup). byo (bring-your-own) keeps them in your own AWS account, which the platform reaches through a cross-account IAM role you create.

Base path: /api/v1/identity
Auth (server / SDK): X-API-Key: hikigai_…, X-Project-ID: YOUR_PROJECT_ID, and User-Agent: hikigai-sdk/… (required — the platform only accepts raw API keys from SDK user agents). The AppSDK sends the same values as Authorization: Bearer hikigai_… plus those headers.
Auth (JWT): Authorization: Bearer <jwt> from POST /api/v1/auth/exchange with X-Project-ID.

Browser note: Identity endpoints cannot be called directly from a browser (CORS + User-Agent policy). Call them from your backend or the AppSDK — the included identity test harness proxies requests with the correct headers.

Scopes

Each endpoint requires one scope on your API key. End users hitting auth endpoints from your app use invoke; one-time setup uses manage / read.

Scope	Used by	Endpoints
`invoke`	Your app, per end user	signup, confirm, login, refresh, logout, forgot-password, reset-password, change-password, MFA, SSO sign-in, QR login
`manage`	Setup & admin	enable, configure SSO, issue QR badge, BYO test, update end-user profile (role, etc.), disable MFA
`read`	Setup & admin	get config, BYO setup

Typical integration flow

Every call below uses the same three headers (see each endpoint for full cURL). Replace YOUR_PROJECT_ID, YOUR_APP_ID, and hikigai_your_api_key.

# 0. Check pool is active
GET /api/v1/identity/apps/YOUR_APP_ID

# 1. Sign up an end user
POST /api/v1/identity/signup
{ "app_id": "YOUR_APP_ID", "email": "clinician@hospital.com", "password": "Temp#Pass2026", "first_name": "Asha", "last_name": "Mehta", "role": "clinician", "attributes": { "phone_number": "+14155552671" }, "metadata": { "doctorID": "6278383837" } }

# 1b. Confirm (if the pool requires email verification)
POST /api/v1/identity/confirm
{ "app_id": "YOUR_APP_ID", "email": "clinician@hospital.com", "code": "123456" }

# 2. Log in → OIDC tokens (or MFA challenge)
POST /api/v1/identity/login
{ "app_id": "YOUR_APP_ID", "email": "clinician@hospital.com", "password": "Temp#Pass2026" }

# 2b. If login returns "status": "challenge", finish with:
POST /api/v1/identity/mfa/respond
{ "app_id": "YOUR_APP_ID", "email": "...", "session": "...", "code": "482913" }

# 3. MFA enrollment (uses access_token from login)
POST /api/v1/identity/mfa/associate   → secret_code
POST /api/v1/identity/mfa/verify      → { "status": "SUCCESS" }
POST /api/v1/identity/mfa/set-preference  → { "enabled": true }

# 4. QR badge (admin issues, kiosk exchanges)
POST /api/v1/identity/apps/YOUR_APP_ID/users/clinician%40hospital.com/qr-login
POST /api/v1/identity/qr-login
{ "app_id": "YOUR_APP_ID", "qr_payload": "hk-qr...." }

# Session maintenance
POST /api/v1/identity/refresh   → { "refresh_token": "..." }
POST /api/v1/identity/logout    → { "email": "..." }

# Forgot password (Cognito emails a verification code)
POST /api/v1/identity/forgot-password
{ "app_id": "YOUR_APP_ID", "email": "clinician@hospital.com" }
POST /api/v1/identity/reset-password
{ "app_id": "YOUR_APP_ID", "email": "clinician@hospital.com", "code": "123456", "new_password": "NewTemp#Pass2026" }

# Change password (user is logged in — uses access_token from login)
POST /api/v1/identity/change-password
{ "app_id": "YOUR_APP_ID", "access_token": "...", "current_password": "...", "new_password": "..." }

# Update profile / role (platform EndUser record — use user_id from signup or users list)
PATCH /api/v1/end-users/END_USER_ID
{ "role": "doctor", "first_name": "Asha", "last_name": "Mehta" }

# Get one user's detail (console path — profile + Cognito status)
GET /api/v1/projects/YOUR_PROJECT_ID/apps/YOUR_APP_ID/identity/users/clinician%40hospital.com

# Shared headers for every curl (SDK / server-side only):
curl ... \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'

Setup & status

POST/api/v1/identity/apps/{app_id}/enable

Provision the app's Cognito user pool. Run this once per app. Returns immediately with status 'provisioning' or 'active'.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "mode": "managed",                      // "managed" or "byo"
  "enabled_methods": ["password", "mfa", "qr", "sso"],
  "byo_role_arn": null,                   // required when mode = "byo"
  "byo_account_id": null
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/apps/YOUR_APP_ID/enable' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{ "mode": "managed", "enabled_methods": ["password", "mfa", "qr"] }'

Response

{
  "app_id": "app_123",
  "project_id": "proj_123",
  "mode": "managed",
  "status": "active",
  "cognito_pool_id": "us-east-2_aBcD1234",
  "cognito_client_id": "1h57kf5a2...",
  "cognito_region": "us-east-2",
  "enabled_methods": ["password", "mfa", "qr"],
  "error_message": null
}

GET/api/v1/identity/apps/{app_id}

Get the app's identity config and provisioning status.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/apps/YOUR_APP_ID' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1'

Response

{
  "app_id": "app_123",
  "project_id": "proj_123",
  "mode": "managed",
  "status": "active",
  "cognito_pool_id": "us-east-2_aBcD1234",
  "cognito_client_id": "1h57kf5a2...",
  "cognito_region": "us-east-2",
  "enabled_methods": ["password", "mfa", "qr"],
  "error_message": null
}

End-user accounts

Console management path: /api/v1/projects/{project_id}/apps/{app_id}/identity
Permissions: apps:read to list users; apps:update to create, import, or delete.
Auth: API key (Authorization: Bearer hikigai_…) or session JWT from POST /api/v1/auth/exchange.

GET/api/v1/projects/{project_id}/apps/{app_id}/identity/users

List end users registered in the app's Cognito pool. Used by the Developer Console User Management tab.

Request Headers

Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Default	Description
`limit`	50	Max 200 per page
`offset`	0	Pagination offset

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/projects/YOUR_PROJECT_ID/apps/YOUR_APP_ID/identity/users' \
  --header 'Authorization: Bearer YOUR_TOKEN'

Response

{
  "users": [
    {
      "id": "eu_abc123",
      "project_id": "proj_123",
      "first_name": "Asha",
      "last_name": "Mehta",
      "email": "clinician@hospital.com",
      "role": "clinician",
      "external_subject": null,
      "is_active": true,
      "metadata": { "doctorID": "6278383837" },
      "created_at": "2026-06-11T12:00:00Z",
      "last_verified_at": null
    }
  ]
}

Two IDs per user: id is the platform-local record id (EndUser.id) — generated the moment the user is created and always present, even before first login. Use it for platform-side references (QR/PIN credentials, audit logs, joins). external_subject is the Cognito subject (a.k.a. user_sub) — the authentication identity; it is null until the user is synced/confirmed with Cognito, and matches the sub claim in the login id_token.

POST/api/v1/identity/signup

Register a new end user in the app's pool. If the pool requires confirmation, follow with /identity/confirm; otherwise the user can log in right away.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "email": "clinician@hospital.com",
  "password": "Temp#Pass2026",
  "first_name": "Asha",                   // optional
  "last_name": "Mehta",                   // optional
  "role": "clinician",                    // optional — app-domain role (stored on EndUser)
  "attributes": {                         // optional — Cognito user attributes (string values)
    "phone_number": "+14155552671"        // E.164 format; other Cognito attrs also allowed
  },
  "metadata": { "doctorID": "6278383837" } // optional — opaque app JSON (any shape)
}

Attributes vs metadata: these are not interchangeable.

attributes — Cognito profile fields. Values must be strings. Keys must be Cognito attributes (or custom attributes defined on the pool), e.g. phone_number, given_name, custom:…. Unknown keys can cause Cognito to reject signup.
metadata — opaque app-specific JSON object (any shape). Stored on the platform EndUser record and, when the pool supports it, mirrored to Cognito as custom:metadata (JSON string, max 2048 chars). Use for things like doctorID, clinic id, flags — not for Cognito identity fields.

Phone number: pass it in attributes, not metadata:

{ "attributes": { "phone_number": "+14155552671" } }

Use E.164 format (+ and country code). It is stored in Cognito and returned under cognito.phone_number on GET …/identity/users/{email}.

Role on signup: role is stored on the platform EndUser record (e.g. clinician, nurse, doctor). It is not sent to Cognito as a custom attribute. Pass it as a top-level field or inside attributes as role / custom:role (those keys are stripped out of Cognito attrs and mapped to EndUser.role). To change role later, use PATCH /api/v1/end-users/{user_id}.

Metadata on signup: metadata is an optional JSON object — pass any keys/values your app needs (e.g. doctorID, clinic id, flags). It is not for Cognito attributes like phone. Stored on the platform EndUser record and, when the pool supports it, mirrored to Cognito as custom:metadata (JSON string, max 2048 chars). Returned by the users list and GET .../identity/users/{email}. Update later via PATCH /api/v1/end-users/{user_id}.

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/signup' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "email": "clinician@hospital.com",
    "password": "Temp#Pass2026",
    "first_name": "Asha",
    "last_name": "Mehta",
    "role": "clinician",
    "attributes": { "phone_number": "+14155552671" },
    "metadata": { "doctorID": "6278383837" }
  }'

Response (201)

{
  "user_sub": "a1b2c3d4-....",   // Cognito subject; null until the user is confirmed
  "user_id": "eu_abc123",         // platform-local EndUser.id (always present)
  "email": "clinician@hospital.com",
  "confirmed": false
}

User IDs on signup: user_id is the platform-local EndUser.id — created immediately and always returned, so use it as the stable handle for the user. user_sub is the Cognito subject and may be null until the account is confirmed (auto-confirm pools return it right away). The same two IDs are returned by /identity/login and the users list.

POST/api/v1/identity/confirm

Confirm a signup with the code emailed to the user.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "email": "clinician@hospital.com",
  "code": "123456"
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/confirm' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "email": "clinician@hospital.com",
    "code": "123456"
  }'

Response (200)

{
  "success": true,
  "message": "Account confirmed"
}

POST/api/v1/identity/login

Authenticate an end user. Returns OIDC tokens, or an MFA challenge if multi-factor is required.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "email": "clinician@hospital.com",
  "password": "Temp#Pass2026"
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/login' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "email": "clinician@hospital.com",
    "password": "Temp#Pass2026"
  }'

Response — success

{
  "status": "authenticated",
  "id_token": "eyJraWQiOi...",
  "access_token": "eyJraWQiOi...",
  "refresh_token": "eyJjdHkiOi...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "user_sub": "a1b2c3d4-....",   // Cognito subject (same as the id_token 'sub' claim)
  "user_id": "eu_abc123"          // platform-local end-user id (EndUser.id)
}

User identifiers: user_sub is the Cognito subject (the authentication identity, equal to the sub claim inside the id_token). user_id is the platform-local EndUser.id returned by the users list. Both are provided so you don't have to decode the JWT — use user_id for platform-side references and user_sub to tie back to the auth token. They are only present when status is authenticated.

Response — MFA required

{
  "status": "challenge",
  "challenge_name": "SOFTWARE_TOKEN_MFA",
  "session": "AYABeF..."
}

MFA challenge: when status is challenge or challenge_name is present, collect the user's TOTP code and call POST /api/v1/identity/mfa/respond with the returned session to finish the login and receive tokens.

POST/api/v1/identity/refresh

Exchange a refresh token for fresh access and ID tokens.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "refresh_token": "eyJjdHkiOi..."
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/refresh' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "refresh_token": "eyJjdHkiOi..."
  }'

Response

{
  "status": "authenticated",
  "id_token": "eyJraWQiOi...",
  "access_token": "eyJraWQiOi...",
  "refresh_token": "eyJjdHkiOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

POST/api/v1/identity/logout

Globally sign the user out, revoking their refresh tokens.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "email": "clinician@hospital.com"
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/logout' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "email": "clinician@hospital.com"
  }'

Response

{
  "success": true,
  "message": "Logged out"
}

Password management

Reset a forgotten password via email verification code (sent by Cognito), or change the password when the user is already logged in. All three endpoints require the invoke scope.

POST/api/v1/identity/forgot-password

Request a password-reset verification code. Cognito emails the code to the user if the account exists. Does not change the password yet.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "email": "clinician@hospital.com"
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/forgot-password' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "email": "clinician@hospital.com"
  }'

Response (200)

{
  "success": true,
  "message": "If an account exists for this email, a password reset code has been sent."
}

Email delivery: the verification code is sent by AWS Cognito to the user's email — not by the Hikigai API directly. Follow with POST /api/v1/identity/reset-password once the user enters the code.

POST/api/v1/identity/reset-password

Set a new password using the verification code from the forgot-password email.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "email": "clinician@hospital.com",
  "code": "123456",
  "new_password": "NewTemp#Pass2026"
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/reset-password' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "email": "clinician@hospital.com",
    "code": "123456",
    "new_password": "NewTemp#Pass2026"
  }'

Response (200)

{
  "success": true,
  "message": "Password reset successfully"
}

POST/api/v1/identity/change-password

Change password for a logged-in user who knows their current password. Requires the access_token from login.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "access_token": "eyJraWQiOi...",
  "current_password": "Temp#Pass2026",
  "new_password": "NewTemp#Pass2026"
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/change-password' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "access_token": "eyJraWQiOi...",
    "current_password": "Temp#Pass2026",
    "new_password": "NewTemp#Pass2026"
  }'

Response (200)

{
  "success": true,
  "message": "Password changed successfully"
}

Multi-factor auth (TOTP)

Enroll a user's authenticator app, then require it at login. The associate step returns a secret you render as an otpauth:// QR code for Google Authenticator, Authy, etc.
Typical enroll flow: POST /identity/login (user password) → POST /identity/mfa/associate → render QR → POST /identity/mfa/verify → POST /identity/mfa/set-preference with enabled: true.
Admin disable: POST /api/v1/end-users/{user_id}/mfa/disable (manage scope) when the user cannot sign in to turn MFA off themselves.

POST/api/v1/identity/mfa/associate

Begin TOTP enrollment for a signed-in user. Returns the shared secret to display as a QR code.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "access_token": "eyJraWQiOi..."        // from login
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/mfa/associate' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "access_token": "eyJraWQiOi..."
  }'

Response

{
  "secret_code": "JBSWY3DPEHPK3PXP",
  "session": null
}

POST/api/v1/identity/mfa/verify

Verify the first TOTP code to finish enrollment.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "access_token": "eyJraWQiOi...",
  "code": "482913",
  "device_name": "iPhone Authenticator"   // optional
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/mfa/verify' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "access_token": "eyJraWQiOi...",
    "code": "482913",
    "device_name": "iPhone Authenticator"
  }'

Response

{
  "status": "SUCCESS"
}

POST/api/v1/identity/mfa/set-preference

Turn TOTP MFA on or off for a user.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "access_token": "eyJraWQiOi...",
  "enabled": true
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/mfa/set-preference' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "access_token": "eyJraWQiOi...",
    "enabled": true
  }'

Response

{
  "success": true,
  "message": "MFA preference updated"
}

POST/api/v1/identity/mfa/respond

Complete a login that returned an MFA challenge. Returns OIDC tokens.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "email": "clinician@hospital.com",
  "session": "AYABeF...",                 // from the login challenge
  "code": "482913"
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/mfa/respond' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "email": "clinician@hospital.com",
    "session": "AYABeF...",
    "code": "482913"
  }'

Response

{
  "status": "authenticated",
  "id_token": "eyJraWQiOi...",
  "access_token": "eyJraWQiOi...",
  "refresh_token": "eyJjdHkiOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

QR badge login

Issue a per-user QR credential a clinician can scan to sign in without typing a password — ideal for shared workstations. Issue the badge once (admin), then exchange a scanned payload for tokens at the kiosk.

POST/api/v1/identity/apps/{app_id}/users/{email}/qr-login

Issue a QR badge credential for a user. No request body — email is in the path (URL-encode @ as %40). The payload is shown once — encode it into the badge.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1

cURL Example

curl --location --request POST 'https://backend.hikigaiplatform.io/api/v1/identity/apps/YOUR_APP_ID/users/clinician%40hospital.com/qr-login' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1'

Response (201)

Returns qr_payload and qr_code_png_base64. May also return 200 on re-issue.

{
  "credential_id": "cred_123",
  "end_user_id": "eu_123",
  "email": "clinician@hospital.com",
  "qr_payload": "HKG1....",
  "qr_code_png_base64": "iVBORw0KGgo..."
}

POST/api/v1/identity/qr-code/render

Render a qr_payload (or any text) as a PNG QR image. Returns image/png.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{ "data": "HKG1...." }

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/qr-code/render' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{ "data": "HKG1...." }' \
  -o badge-qr.png

Response (200)

Binary PNG image (Content-Type: image/png).

POST/api/v1/identity/qr-login

Exchange a scanned QR payload for OIDC tokens.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "qr_payload": "hk-qr.eyJ1Ijoi..."
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/qr-login' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "qr_payload": "hk-qr.eyJ1Ijoi..."
  }'

Response

{
  "status": "authenticated",
  "id_token": "eyJraWQiOi...",
  "access_token": "eyJraWQiOi...",
  "refresh_token": "eyJjdHkiOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

End-user profile & role

Fetch or update an end user's profile (role, name, metadata, active status). Email is immutable — it is the Cognito login identity.
Fetch by email (console path): GET /api/v1/projects/{project_id}/apps/{app_id}/identity/users/{email} — merged platform + Cognito detail. Auth: Bearer token; permission apps:read.
Fetch / update by user id: GET or PATCH /api/v1/end-users/{user_id} — use user_id from signup (user_id field), the users list, or the console detail response id. Auth: SDK headers or console session + X-Project-ID; scopes read (GET) or manage (PATCH). App developers with apps:update get manage.

GET/api/v1/projects/{project_id}/apps/{app_id}/identity/users/{email}

Get full detail for one end user by email: platform profile (role, name, metadata) merged with live Cognito status (MFA, enabled, email verified).

Request Headers

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Path Parameters

project_id, app_id — your project and app ids.
email — the end user's email (URL-encode @, e.g. test1%40gmail.com).

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/projects/YOUR_PROJECT_ID/apps/YOUR_APP_ID/identity/users/test1%40gmail.com' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json'

Response

{
  "id": "eu_abc123",
  "email": "test1@gmail.com",
  "first_name": "Asha",
  "last_name": "Mehta",
  "role": "clinician",
  "is_active": true,
  "external_subject": "a1b2c3d4-....",
  "created_at": "2026-06-11T12:00:00Z",
  "last_login_at": "2026-06-12T08:30:00Z",
  "metadata": { "doctorID": "6278383837" },
  "cognito": {
    "user_sub": "a1b2c3d4-....",
    "status": "CONFIRMED",
    "enabled": true,
    "email_verified": true,
    "mfa_enabled": false,
    "mfa_methods": [],
    "preferred_mfa": null,
    "created_at": "2026-06-11T12:00:00Z",
    "last_modified_at": "2026-06-12T08:30:00Z",
    "phone_number": "+14155552671",
    "metadata": { "doctorID": "6278383837" }
  }
}

Merged view: top-level fields come from the platform EndUser index (role, names, metadata). The cognito object is live pool status; it may be null if Cognito is temporarily unreachable. Cognito attributes set via signup attributes (e.g. phone_number) appear under cognito. When metadata was stored in Cognito, cognito.metadata contains the parsed JSON from custom:metadata.

GET/api/v1/end-users/{user_id}

Get an end user's platform profile by user_id (SDK path). Lighter than the email lookup — no live Cognito block.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1

Path Parameters

user_id — platform-local EndUser.id (from signup user_id, users list id, or GET /api/v1/end-users).

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/end-users/END_USER_ID' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1'

Response (200)

{
  "id": "eu_abc123",
  "project_id": "proj_123",
  "first_name": "Asha",
  "last_name": "Mehta",
  "email": "clinician@hospital.com",
  "role": "clinician",
  "external_subject": "a1b2c3d4-....",
  "is_active": true,
  "qr_issued": false,
  "metadata": null,
  "created_at": "2026-06-11T12:00:00Z",
  "last_verified_at": "2026-06-12T08:30:00Z"
}

PATCH/api/v1/end-users/{user_id}

Update an end user's profile. All body fields are optional — send only what you want to change. Email cannot be updated.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Path Parameters

user_id — platform-local EndUser.id (from signup response user_id, users list id, or GET /api/v1/end-users).

Request Body

{
  "role": "doctor",                       // optional — app-domain role
  "first_name": "Asha",                   // optional
  "last_name": "Mehta",                   // optional
  "phone_number": "+14155552671",         // optional — Cognito attribute (E.164); "" clears
  "metadata": { "department": "cardiology" },  // optional
  "is_active": true                       // optional — disable the user
}

cURL Example

curl --location --request PATCH 'https://backend.hikigaiplatform.io/api/v1/end-users/END_USER_ID' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "doctor"
  }'

Response (200)

{
  "id": "eu_abc123",
  "project_id": "proj_123",
  "first_name": "Asha",
  "last_name": "Mehta",
  "email": "clinician@hospital.com",
  "role": "doctor",
  "external_subject": "a1b2c3d4-....",
  "is_active": true,
  "qr_issued": false,
  "metadata": null,
  "created_at": "2026-06-11T12:00:00Z",
  "last_verified_at": "2026-06-12T08:30:00Z"
}

Immutable fields: email, external_subject, password, and ids cannot be changed here. Sending them returns 422. To change a login email, create a new account (or delete + recreate). Use the password endpoints to change passwords. phone_number updates the Cognito attribute (E.164, e.g. +14155552671); send an empty string to clear it.

POST/api/v1/end-users/{user_id}/mfa/disable

Admin-disable TOTP MFA for an end user (manage scope). Use when the user cannot sign in to turn MFA off themselves — unlike POST /identity/mfa/set-preference, this does not require the user's access token.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Path Parameters

user_id — platform-local EndUser.id.

cURL Example

curl --location --request POST 'https://backend.hikigaiplatform.io/api/v1/end-users/END_USER_ID/mfa/disable' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1'

Response (200)

{ "success": true, "message": "MFA disabled" }

Platform credentials (QR & PIN badges)

Manage per-user QR badges and PINs on the platform identity index (separate from Cognito pool users above). Base path: /api/v1/end-users.
Auth: same SDK headers as other identity endpoints (X-API-Key, X-Project-ID, User-Agent: hikigai-sdk/…).
Scopes: read to list credentials; manage to issue, rotate, or revoke.

GET/api/v1/end-users/{user_id}/credentials

List all credentials (QR badges, PINs) for an end user. Use the id field from each item as CREDENTIAL_ID when revoking or rotating.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1

Path Parameters

user_id — the end-user ID from POST /api/v1/end-users (response id), GET /api/v1/end-users (each end_users[].id), or GET /api/v1/end-users/{id}.

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/end-users/END_USER_ID/credentials' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1'

Response

{
  "credentials": [
    {
      "id": "cred_abc123",
      "end_user_id": "eu_abc123",
      "credential_type": "qr",
      "status": "active",
      "issued_at": "2026-06-11T12:00:00Z",
      "expires_at": null,
      "last_used_at": "2026-06-12T08:30:00Z"
    },
    {
      "id": "cred_def456",
      "end_user_id": "eu_abc123",
      "credential_type": "pin",
      "status": "active",
      "issued_at": "2026-06-11T12:05:00Z",
      "expires_at": null,
      "last_used_at": null
    }
  ]
}

Where to get CREDENTIAL_ID: the id field on each object in this response. You can also capture it when a credential is created —credential_id from POST …/credentials/qr or POST …/credentials/{credential_id}/rotate, and id from POST …/credentials/pin.

DELETE/api/v1/end-users/{user_id}/credentials/{credential_id}

Revoke a QR badge or PIN credential. The credential cannot be used for verification after revocation.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1

Path Parameters

user_id — end-user ID (see list credentials above).
credential_id — from GET …/credentials (each credentials[].id), or from the issue/rotate response when the credential was first created.

cURL Example

curl --location --request DELETE 'https://backend.hikigaiplatform.io/api/v1/end-users/END_USER_ID/credentials/CREDENTIAL_ID' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1'

Response

{
  "success": true,
  "message": "Credential revoked"
}

Single sign-on & social

Let users sign in with Google, Apple, Okta, Azure AD, SAML, or any OIDC provider. Configure the provider once, then run the standard authorize-redirect / code-exchange flow.

POST/api/v1/identity/apps/{app_id}/sso

Add or update an SSO / social provider on the app's pool.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "provider_name": "Google",
  "provider_type": "Google",
  "provider_details": {
    "client_id": "...",
    "client_secret": "...",
    "authorize_scopes": "openid email profile"
  },
  "callback_urls": ["https://yourapp.com/auth/callback"],
  "attribute_mapping": { "email": "email" },
  "scopes": ["openid", "email", "profile"]
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/apps/YOUR_APP_ID/sso' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "provider_name": "Google",
    "provider_type": "Google",
    "provider_details": {
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "authorize_scopes": "openid email profile"
    },
    "callback_urls": ["https://yourapp.com/auth/callback"],
    "attribute_mapping": { "email": "email" },
    "scopes": ["openid", "email", "profile"]
  }'

Response

{
  "app_id": "app_123",
  "project_id": "proj_123",
  "mode": "managed",
  "status": "active",
  "cognito_pool_id": "us-east-2_aBcD1234",
  "cognito_client_id": "1h57kf5a2...",
  "cognito_region": "us-east-2",
  "enabled_methods": ["password", "mfa", "qr", "sso"],
  "error_message": null
}

POST/api/v1/identity/sso/authorize-url

Build the hosted-UI authorize URL to redirect the user to for sign-in.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "redirect_uri": "https://yourapp.com/auth/callback",
  "provider": "Google",                    // optional
  "scopes": ["openid", "email", "profile"] // optional
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/sso/authorize-url' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "redirect_uri": "https://yourapp.com/auth/callback",
    "provider": "Google"
  }'

Response

{
  "authorize_url": "https://app-123.auth.us-east-2.amazoncognito.com/oauth2/authorize?..."
}

POST/api/v1/identity/sso/token

Exchange the authorization code from the callback for OIDC tokens.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "app_id": "app_123",
  "code": "auth-code-from-callback",
  "redirect_uri": "https://yourapp.com/auth/callback"
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/sso/token' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_id": "app_123",
    "code": "auth-code-from-callback",
    "redirect_uri": "https://yourapp.com/auth/callback"
  }'

Response

{
  "status": "authenticated",
  "id_token": "eyJraWQiOi...",
  "access_token": "eyJraWQiOi...",
  "refresh_token": "eyJjdHkiOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Bring-your-own Cognito

To keep users in your own AWS account, create a cross-account IAM role from the template below, then enable the app with mode: "byo" and the role ARN.

GET/api/v1/identity/byo/setup

Get the CloudFormation template and the trust values (Hikigai account ID + ExternalId) to create the cross-account role.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/byo/setup' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1'

Response

{
  "hikigai_account_id": "439563881130",
  "external_id": "hikigai-app-123",
  "template": "AWSTemplateFormatVersion: '2010-09-09' ..."
}

POST/api/v1/identity/byo/test

Verify the platform can assume your cross-account role before enabling BYO.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID
User-Agent: hikigai-sdk/0.0.1
Content-Type: application/json

Request Body

{
  "role_arn": "arn:aws:iam::123456789012:role/HikigaiIdentityProvisioningRole",
  "region": "us-east-2"                    // optional
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/identity/byo/test' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'User-Agent: hikigai-sdk/0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "role_arn": "arn:aws:iam::123456789012:role/HikigaiIdentityProvisioningRole",
    "region": "us-east-2"
  }'

Response

{
  "ok": true,
  "account_id": "123456789012",
  "error": null
}

Prefer an SDK? The same flow is available as client.identity in the Python and Node App SDKs.

Object Storage

Platform-managed object storage for deployed apps. Upload PDFs, images, audio, and other documents scoped to a project and app. Files are stored in a private AWS S3 bucket — they are never public. Access is via time-limited signed URLs generated by the platform API.

How signed URLs work: The Hikigai API does not proxy file bytes. When you call /storage/{object_id}/url, the backend asks AWS S3 for a presigned GET URL (SigV4). The response URL points directly to S3 (e.g. https://hikigai-apps-storage-….s3.amazonaws.com/…). Your app or browser fetches the file from S3 until the URL expires.

Base path: /api/v1/projects/{project_id}/apps/{app_id}/storage
Permissions: apps:read for list, get, stats, and signed URLs; apps:update for upload and delete.
Auth: API key (Authorization: Bearer hikigai_…) or session JWT.

POST/api/v1/projects/{project_id}/apps/{app_id}/storage/upload

Upload a file to platform storage. Returns object metadata and a 1-hour signed URL for immediate use.

Request Headers

Authorization: Bearer hikigai_your_api_key
Content-Type: multipart/form-data
X-Project-ID: YOUR_PROJECT_ID

Form Fields

Field	Type	Description
`file`	binary	Required. Max 100MB. PDF, images, audio, zip, etc.
`metadata`	JSON string	Optional key-value metadata stored with the object. Common keys: `description`, `agent_id`, `generated_by`. Shown in the Developer Portal Documents tab.
`ttl`	integer	Optional auto-expiry in seconds (omit = permanent)
`filename`	string	Optional display name override

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/projects/YOUR_PROJECT_ID/apps/YOUR_APP_ID/storage/upload' \
  --header 'Authorization: Bearer hikigai_your_api_key' \
  --form 'file=@report.pdf' \
  --form 'metadata={"description":"Monthly report","agent_id":"pdf-generator"}' \
  --form 'ttl=86400'

Response (201)

{
  "object_id": "uuid",
  "object_key": "projects/{pid}/apps/{aid}/{object_id}/report.pdf",
  "original_filename": "report.pdf",
  "content_type": "application/pdf",
  "size_bytes": 245120,
  "signed_url": "https://hikigai-apps-storage-....s3.amazonaws.com/...?X-Amz-...",
  "expires_at": null,
  "created_at": "2026-06-11T12:00:00Z"
}

GET/api/v1/projects/{project_id}/apps/{app_id}/storage

List stored objects for an app (paginated).

Query Parameters

Parameter	Default	Description
`page`	1	Page number
`limit`	20	Max 100 per page
`status`	active	active \| expired \| all
`content_type`	—	Filter by exact MIME type (e.g. `application/pdf`)
`content_type_prefix`	—	Filter by MIME prefix (e.g. `image/` or `audio/`)
`search`	—	Filename search
`sort`	created_at	created_at \| size_bytes \| original_filename
`order`	desc	asc \| desc

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/projects/YOUR_PROJECT_ID/apps/YOUR_APP_ID/storage?status=active&limit=20' \
  --header 'Authorization: Bearer hikigai_your_api_key'

Response

{
  "objects": [
    {
      "id": "uuid",
      "original_filename": "report.pdf",
      "content_type": "application/pdf",
      "size_bytes": 245120,
      "metadata": { "description": "Monthly report", "agent_id": "pdf-generator" },
      "status": "active",
      "upload_source": "sdk",
      "expires_at": null,
      "created_at": "2026-06-11T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "total_pages": 1
}

GET/api/v1/projects/{project_id}/apps/{app_id}/storage/{object_id}

Get metadata for a single stored object (does not return file bytes).

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/projects/YOUR_PROJECT_ID/apps/YOUR_APP_ID/storage/OBJECT_ID' \
  --header 'Authorization: Bearer hikigai_your_api_key'

GET/api/v1/projects/{project_id}/apps/{app_id}/storage/{object_id}/url

Generate a time-limited S3 signed URL for download. Default TTL 1 hour; max 7 days.

Query Parameters

ttl=3600   # seconds (min 60, max 604800)

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/projects/YOUR_PROJECT_ID/apps/YOUR_APP_ID/storage/OBJECT_ID/url?ttl=3600' \
  --header 'Authorization: Bearer hikigai_your_api_key'

Response

{
  "object_id": "uuid",
  "signed_url": "https://hikigai-apps-storage-....s3.amazonaws.com/projects/.../file.pdf?X-Amz-Algorithm=...",
  "expires_in": 3600,
  "expires_at": "2026-06-11T13:00:00Z"
}

Expiry: When the signed URL expires, S3 returns an access-denied response — call this endpoint again to get a fresh URL.

GET/api/v1/projects/{project_id}/apps/{app_id}/storage/{object_id}/download

Redirect (302) to a fresh S3 signed URL — convenient for browser downloads.

Query Parameters

ttl=3600   # optional; seconds (min 60, max 604800). Defaults to platform signed-URL TTL.

cURL Example

curl -L --location 'https://backend.hikigaiplatform.io/api/v1/projects/YOUR_PROJECT_ID/apps/YOUR_APP_ID/storage/OBJECT_ID/download' \
  --header 'Authorization: Bearer hikigai_your_api_key' \
  -o report.pdf

DELETE/api/v1/projects/{project_id}/apps/{app_id}/storage/{object_id}

Delete an object from S3 and mark it deleted in the platform database.

cURL Example

curl --location --request DELETE 'https://backend.hikigaiplatform.io/api/v1/projects/YOUR_PROJECT_ID/apps/YOUR_APP_ID/storage/OBJECT_ID' \
  --header 'Authorization: Bearer hikigai_your_api_key'

Response (200)

{
  "success": true,
  "message": "Storage object deleted"
}

GET/api/v1/projects/{project_id}/apps/{app_id}/storage/stats

Storage usage stats for the app (file count, total size, PDF count, expiring soon).

Response

{
  "total_objects": 5,
  "active_objects": 4,
  "expired_objects": 1,
  "total_size_bytes": 12582912,
  "total_size_human": "12.0 MB",
  "pdf_count": 3,
  "expiring_soon_count": 0
}

upload_source on list/get responses is sdk when the request uses an API key (Authorization: Bearer hikigai_…), otherwise portal (browser session upload).

AppSDK & AgentSDK

Both SDKs expose the same client.storage client from a deployed app or agent:

from hikigai.appsdk import AppClient

client = AppClient(api_key="hikigai_...", project_id="...")

# Upload
with open("report.pdf", "rb") as f:
    result = client.storage.upload(
        app_id="your-app-id",
        file=f,
        filename="report.pdf",
        content_type="application/pdf",
        metadata={
            "description": "Monthly report",
            "agent_id": "pdf-generator",
        },
        ttl=86400,
    )
print(result.signed_url)  # S3 presigned URL

# Fresh signed URL later
url = client.storage.signed_url(app_id="your-app-id", object_id=result.object_id, ttl=3600)

# List, get, delete
objects = client.storage.list(app_id="your-app-id")
info = client.storage.get(app_id="your-app-id", object_id=result.object_id)
client.storage.delete(app_id="your-app-id", object_id=result.object_id)

Live Sessions

Bidirectional WebSocket at /api/v1/agents/{agent_slug}/live. Each input turn uses start → one or more data frames → end. Set modality to "text" or "audio" on the start frame and on every data frame.

WS/api/v1/agents/{agent_slug}/live

Live bidirectional streaming. Protocol matches AppSDK StreamSession and the agent container /live handler.

Connection URL

wss://backend.hikigaiplatform.io/api/v1/agents/{agent_slug}/live

Protocol summary

Direction	Frames
Client → server	`auth` (first only) → per turn: `start` → `data` (×N) → `end`. Optional: `disconnect` to end the session.
Server → client	`start` → `data` (×N) → `end`, or `error`
`modality`	`"text"` — `content` is a string. `"audio"` — `content` is base64 PCM; include `mime_type` (e.g. `audio/pcm;rate=16000`).

Step 1 — Auth (first frame)

10-second timeout. Send api_key or access_token — not both.

{"type": "auth", "api_key": "hikigai_your_api_key", "session_id": "550e8400-e29b-41d4-a716-446655440000"}

Or with a JWT from POST /api/v1/auth/exchange:

{"type": "auth", "access_token": "YOUR_JWT_TOKEN", "session_id": "550e8400-e29b-41d4-a716-446655440000"}

Step 2 — Send one input turn

Text (`modality: "text"`)

{"type": "start", "modality": "text"}
{"type": "data",  "modality": "text", "content": "Summarize the vitals from this visit."}
{"type": "end"}

Audio (`modality: "audio"`)

One start per utterance, then stream PCM chunks as data frames, then end. Mono 16-bit PCM at 16 kHz (resample in the client if the mic uses 44.1/48 kHz).

{"type": "start", "modality": "audio"}
{"type": "data", "modality": "audio", "content": "<base64-pcm-chunk>", "mime_type": "audio/pcm;rate=16000"}
// ... more data frames while the user speaks ...
{"type": "end"}

Step 3 — Server response (per turn)

Text-in agents (`modality: "text"` on output)

{"type": "start"}
{"type": "data", "modality": "text", "content": "Vitals are stable..."}
{"type": "end", "interrupted": false}

Audio-in transcription (`source: "input_transcription"`)

When the deployed agent uses audio input, transcript text arrives on data frames with modality: "text" and source: "input_transcription". Each partial replaces the previous string (do not append). Ignore output_transcription for pure transcription UIs.

{"type": "start"}
{"type": "data", "modality": "text", "content": "...", "source": "input_transcription", "partial": true}
{"type": "data", "modality": "text", "content": "...", "source": "input_transcription", "partial": false, "finished": true}
{"type": "end", "interrupted": false}
{"type": "error", "message": "..."}

Step 4 — Close

{"type": "end"}
{"type": "disconnect"}

AppSDK StreamSession.close() closes the WebSocket directly; disconnect is optional for raw clients.

Python AppSDK — text turn

From StreamSession — start(modality="text"), then send_data(str), then end():

async with client.live("YOUR_AGENT_SLUG", session_id=session_id) as session:
    await session.start(modality="text")
    await session.send_data("Summarize the vitals from this visit.")
    await session.end()
    async for event in session:
        if event["type"] == "data" and event.get("modality") == "text":
            print(event["content"], end="", flush=True)
        elif event["type"] == "end":
            break

Python AppSDK — audio turn

start(modality="audio") once, then send_data(bytes, mime_type=...) per chunk (bytes are base64-encoded by the SDK), then end():

async with client.live("YOUR_AGENT_SLUG", session_id=session_id) as session:
    await session.start(modality="audio")
    await session.send_data(pcm_chunk, mime_type="audio/pcm;rate=16000")
    await session.end()
    async for event in session:
        if event["type"] == "data" and event.get("source") == "input_transcription":
            transcript = event["content"]  # replace UI text each partial
        elif event["type"] == "end":
            break

wscat example (text turn)

wscat -c "wss://backend.hikigaiplatform.io/api/v1/agents/YOUR_AGENT_SLUG/live"

{"type": "auth", "api_key": "hikigai_your_api_key", "session_id": "550e8400-e29b-41d4-a716-446655440000"}
{"type": "start", "modality": "text"}
{"type": "data", "modality": "text", "content": "What are the differential diagnoses?"}
{"type": "end"}

Agent config: Deploy-time input_modality / output_modality on the agent determine how the container configures the live model (e.g. audio in + text transcript out).

Session continuity: Reuse session_id across reconnects (Redis TTL ~1 hour).

Rooms

Project-scoped pub/sub over WebSocket. Multiple clients join the same room name within a project and exchange JSON events — useful for fan-out (e.g. one client publishes transcript updates, others subscribe in real time). Rooms are namespaced server-side as {project_id}:{room} so members of one project never see another project's traffic.

Use a project-scoped API key (the key must be tied to a project). Console JWTs and short-lived room_token credentials are also supported.

Room naming, creation & lifecycle

There is no separate "create room" API. You choose a room name in your application and send a join frame — the platform creates the room implicitly the first time anyone joins that name within your project.

Question	Answer
Who picks the room name?	Your application — not the platform. You pass any valid string in the `join` frame (e.g. `consultation-42`, `session-abc`).
When is a room created?	On the first `join` to that name. No pre-registration step.
Which client creates it?	Whoever joins first. A publisher and a subscriber are equal — if the subscriber connects before the publisher, the subscriber creates the room and the publisher joins it later.
How does the server identify a room?	Internally as `{project_id}:{room_name}`. Your API key determines `project_id`; the `room` field in each frame is the short name you chose.
How do two apps find each other?	They must agree on the same room string outside the protocol — config, URL query param, database record, shared session ID, etc. The platform does not route one client to another's room automatically.
When does a room go away?	When the last member leaves (implicit GC). Rooms are not persisted in a registry.

Typical publisher / subscriber flow

A common pattern is one client that publishes events (e.g. live transcript lines) and one or more clients that only listen. Both follow the same WebSocket steps — connect, auth, join — using the same project API key and same room name:

Publisher                          Subscriber
─────────                          ──────────
1. connect WS                      (idle)
2. auth (api_key)                  (idle)
3. join "consultation-42"   ←── creates room if new
4. publish events                  1. connect WS
                                   2. auth (same project key)
                                   3. join "consultation-42"  ←── joins existing room
                                   4. receive message frames

If the subscriber uses consultation-43 instead of consultation-42, it will never see the publisher's messages — same project, different room. Names are case-sensitive.

Ways to coordinate the room name in your app

Hardcode a shared name in both clients for development
Derive from a domain ID: appointment-{appointment_id}
Pass via URL: ?room=consultation-42
Store in your backend and return it to both clients at login
Use the built-in notifications room name for platform job events

Cross-project isolation: Two projects can both use the name consultation-42 — they are completely separate rooms because the server keys them as {project_a_id}:consultation-42 vs {project_b_id}:consultation-42.

WS/api/v1/rooms/ws

Rooms WebSocket protocol. First frame must be auth; then join, publish, and receive broadcasts.

Connection URL

wss://backend.hikigaiplatform.io/api/v1/rooms/ws

Protocol summary

Direction	Frames
Client → server	`auth` (first only) → `join` → `publish` / `leave` / `who` / `ping`. Optional: `disconnect` to end the session.
Server → client	`ready` → `joined` / `left` → `message` (broadcasts), `presence`, `pong`, or `error`
Room names	1–128 characters: letters, digits, `_`, `.`, `:`, `-`. Must start with a letter or digit (e.g. `consultation-42`, `notifications`).

Step 1 — Connect and authenticate

Open the WebSocket, then send auth within 10 seconds. With a project API key:

{"type": "auth", "api_key": "hikigai_your_project_api_key"}

Or with a JWT from POST /api/v1/auth/exchange (include the project):

{"type": "auth", "access_token": "YOUR_JWT_TOKEN", "project_id": "YOUR_PROJECT_ID"}

Or with a minted room token (see POST /api/v1/rooms/tokens below):

{"type": "auth", "room_token": "YOUR_ROOM_TOKEN"}

On success the server replies with ready and a connection_id:

{"type": "ready", "connection_id": "conn_a1b2c3d4e5f6", "project_id": "YOUR_PROJECT_ID", "capabilities": ["manage", "publish", "subscribe"]}

Step 2 — Join a room (creates it if new)

Send any valid room name. This is the only step that puts you in a room — there is no prior create call. The first client to join a given name within your project creates the room; every later client with the same name joins that room.

{"type": "join", "room": "consultation-42"}

Optional: pass last_seq when rejoining after a disconnect to replay messages you missed (bounded buffer):

{"type": "join", "room": "consultation-42", "last_seq": 12}

Server ack (includes current members and the room's latest sequence number):

{"type": "joined", "room": "consultation-42", "capabilities": ["manage", "publish", "subscribe"], "seq": 0, "members": [{"id": "conn_a1b2c3d4e5f6", "principal": "..."}]}

Before publishing: You must receive joined for that room first. Sending publish while not a member returns an error.

Step 3 — Publish an event

You must be joined to the room. event is your application-defined channel name (1–128 chars); data is any JSON-serializable payload.

{"type": "publish", "room": "consultation-42", "event": "transcript.partial", "data": {"text": "Patient reports mild headache", "turn": 1, "finished": false}}

Final update on the same turn:

{"type": "publish", "room": "consultation-42", "event": "transcript.final", "data": {"text": "Patient reports mild headache since yesterday.", "turn": 1, "finished": true}}

Set echo: true if the publisher should also receive its own message (default is false).

Step 4 — Receive broadcasts

Other members (and server-side publishers) deliver message frames. Use seq for ordering and deduplication on reconnect.

{"type": "message", "room": "consultation-42", "event": "transcript.partial", "data": {"text": "...", "turn": 1, "finished": false}, "seq": 3, "sender": "conn_xyz", "ts": "2026-07-29T12:00:00.000Z"}

Presence updates arrive as presence when members join or leave.

Step 5 — Leave or disconnect

{"type": "leave", "room": "consultation-42"}

Server ack:

{"type": "left", "room": "consultation-42", "reason": "leave"}

To tear down the whole connection, send disconnect or close the WebSocket:

{"type": "disconnect"}

End-to-end example — publisher and subscriber

Two browser tabs (or two apps) using the same project API key and same room name. Tab 1 publishes; Tab 2 only listens. Either tab can connect first — the first join creates the room.

// Tab 1 — publisher (creates room on first join)
wscat -c "wss://backend.hikigaiplatform.io/api/v1/rooms/ws"
{"type": "auth", "api_key": "hikigai_your_project_api_key"}
{"type": "join", "room": "consultation-42"}
// ← joined (members: 1)
{"type": "publish", "room": "consultation-42", "event": "note.updated", "data": {"text": "Follow up in two weeks"}}

// Tab 2 — subscriber (joins the room Tab 1 created)
{"type": "auth", "api_key": "hikigai_your_project_api_key"}
{"type": "join", "room": "consultation-42"}
// ← joined (members: 2)
// ← message { "event": "note.updated", "data": { "text": "Follow up in two weeks" }, ... }

JavaScript client pattern

const ws = new WebSocket("wss://backend.hikigaiplatform.io/api/v1/rooms/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "auth", api_key: "hikigai_your_project_api_key" }));
};

ws.onmessage = (ev) => {
  const frame = JSON.parse(ev.data);
  if (frame.type === "ready") {
    ws.send(JSON.stringify({ type: "join", room: "consultation-42" }));
  } else if (frame.type === "message") {
    console.log(frame.event, frame.data);
  }
};

function publish(event, data) {
  ws.send(JSON.stringify({ type: "publish", room: "consultation-42", event, data }));
}

function disconnect() {
  ws.send(JSON.stringify({ type: "disconnect" }));
  ws.close();
}

Error codes

Code	Meaning
`unauthorized`	Invalid or missing credentials, auth timeout, or project mismatch
`forbidden`	Not allowed to join or publish in this room
`bad_frame`	Malformed JSON, unknown frame type, or invalid room name
`payload_too_large`	Frame or publish payload exceeds size limit (128 KB default)
`rate_limited`	Join or publish rate exceeded
`room_full`	Room member cap reached

Server push: Job lifecycle events (e.g. job.completed) are broadcast to each project's notifications room automatically — join that room to receive them.

POST/api/v1/rooms/tokens

Mint a short-lived room token for end-user clients (scoped room patterns and capabilities).

Request Headers

X-API-Key: hikigai_your_project_api_key
X-Project-ID: YOUR_PROJECT_ID
Content-Type: application/json

Request Body

{
  "rooms": ["consultation-*"],
  "capabilities": ["subscribe", "publish"],
  "principal": "end-user-123",
  "ttl_seconds": 600
}

Use the returned room_token in the WebSocket auth frame instead of an API key when handing credentials to a browser or mobile app.

POST/api/v1/rooms/{room}/publish

Server-side publish without holding a WebSocket — for backends, workers, or services.

Request Headers

X-API-Key: hikigai_your_project_api_key
X-Project-ID: YOUR_PROJECT_ID
Content-Type: application/json

Request Body

{
  "event": "appointment.reminder",
  "data": {"patient_id": "p-001", "slot": "2026-07-30T09:00:00Z"}
}

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/rooms/consultation-42/publish' \
  --header 'X-API-Key: hikigai_your_project_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID' \
  --header 'Content-Type: application/json' \
  --data '{"event": "note.updated", "data": {"text": "Labs ordered"}}'

GET/api/v1/rooms/stats

Hub statistics including backplane health (project-scoped API key required).

Request Headers

X-API-Key: hikigai_your_project_api_key
X-Project-ID: YOUR_PROJECT_ID

Multi-Cloud

Catalog-driven deployment targets for agents, apps, and MCP servers on GCP or AWS. Optional BYOC credentials are managed under /api/v1/cloud/credentials.

GET/api/v1/cloud/catalog

List providers, services, regions, zones, and per-service JSON Schema. Optional workload filter: app | agent | mcp.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID

cURL Example

curl --location 'https://backend.hikigaiplatform.io/api/v1/cloud/catalog?workload=agent' \
  --header 'X-API-Key: hikigai_your_api_key' \
  --header 'X-Project-ID: YOUR_PROJECT_ID'

POST/api/v1/cloud/targets/validate

Dry-run a deployment target (service, region, config) before deploy.

Request Body

{
  "workload": "app",
  "service_id": "gcp-cloud-run",
  "region": "us-central1",
  "config": {"cpu": "1", "memory": "512Mi"}
}

Webhooks (Event Bus)

Project-scoped webhook subscriptions for platform CloudEvents (agent deploy/delete, jobs, invocations, storage). Deliveries are HMAC-SHA256 signed.

GET/api/v1/webhooks

List webhook subscriptions for the project.

Request Headers

X-API-Key: hikigai_your_api_key
X-Project-ID: YOUR_PROJECT_ID

POST/api/v1/webhooks

Create a webhook subscription. The signing secret is returned once.

Request Body

{
  "url": "https://ci.example.com/hooks/hikigai",
  "event_types": ["agent.deployed", "agent.deleted"],
  "description": "deploy notifications"
}

POST/api/v1/webhooks/{id}/test

Send a synthetic webhook.test ping to verify the endpoint.

Also supports rotate-secret, deliveries list, and redelivery.

Need more help? Check the Getting Started guide or review the Platform API Reference.