External access: your first API conversation (preview)

Purpose#

External access lets a business backend call a Onevium assistant through an API or Webhook. This page targets the 1.1.23-beta.7 development preview, not stable 1.1.22. Real public-network and production-business acceptance remains incomplete.

Before you start#

Use an available preview environment. In External Access, create an application, bind an assistant, pass its capability checks, and publish the assistant. Obtain the gateway address, App Key, and endpoint ID. Publishing an assistant is not publishing a stable desktop release.

Start with built-in access; public networking and Docker are optional. Keep the App Key on the business backend and derive subject from an authenticated user, not browser input. Do not expose Onevium's original management port.

First task#

1. In a test backend, set GATEWAY_URL to the displayed gateway address and APP_KEY to the application key. Replace the endpoint placeholder with its real ID. Create a conversation:

curl "$GATEWAY_URL/api/v1/conversations" \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'X-Onevium-Subject: docs-test-user' \
  -H 'Idempotency-Key: docs-create-001' \
  -H 'Content-Type: application/json' \
  --data '{"endpoint_id":"YOUR_ENDPOINT_ID","conversation_key":"docs-demo"}'

2. Save the returned conversation ID as CONVERSATION_ID. Send a message to the new conversation:

curl "$GATEWAY_URL/api/v1/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'X-Onevium-Subject: docs-test-user' \
  -H 'Idempotency-Key: docs-message-001' \
  -H 'Content-Type: application/json' \
  --data '{"expected_generation":1,"input":{"text":"Reply only: Connected"}}'

3. Use the returned run_id to request GET /api/v1/runs/:run_id with the same identity until it has a real terminal state and result. A 202 response means accepted, not completed.
4. Use a new idempotency key for a new message. Keep the original key and body for retries of the same operation. After a context reset, use the actual new generation instead of always sending 1.

Confirm success#

The business conversation, Onevium execution, and Run result correspond to the same request. Closing SSE stops observation, not execution. Query the operation to confirm cancellation or reset. Built-in access cannot accept new requests while its computer is asleep or off.

Common problems#

• 401/403: check the App Key, scopes, and assistant authorization.
• 409: check generation, busy state, and reuse of a key with a different body.
• Accepted but unfinished: inspect device state and approvals instead of creating another execution.

Next steps#

Webhooks use separate signatures and event deduplication. Result callbacks are a separate delivery process, confirmed only by a destination 2xx response. Complete the built-in flow before validating Docker, real TLS/SSH, and business deployment. See channels for related entry points and permissions for authorization boundaries.