Source: docs/integration/getting-started.md

Getting started

This path uses the HTTP channel to verify that your application can send a text

message and receive a synchronous agent response.

1. Receive the access bundle

Ask the Forgium administrator for the following values for the target

environment:

FORGIUM_AGENT_BASE_URL=https://<public-api-host>
FORGIUM_AGENT_API_KEY=mg_xxx

Store the key in the host application's secret manager; do not commit it,

include it in a capability manifest, or put it in logs.

2. Configure the integration

export FORGIUM_AGENT_BASE_URL="https://<public-api-host>"
export FORGIUM_AGENT_API_KEY="mg_xxx"

Confirm the public API is reachable:

curl -fsS "$FORGIUM_AGENT_BASE_URL/health"

Expected response:

{"status":"ok","service":"agent-api"}

3. Send the first message

curl -fsS -X POST "$FORGIUM_AGENT_BASE_URL/v1/channels/http/messages" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "integration-smoke-test",
    "message": {
      "type": "text",
      "body": "Hello, can you help me?"
    },
    "metadata": {
      "source": "integration-smoke-test"
    }
  }'

A successful response contains a conversation_id and an assistant message.

Persist the conversation_id in the host application and send it in later

requests to continue the same conversation.

{
  "conversation_id": "conv_xxx",
  "message": {
    "id": "msg_xxx",
    "role": "assistant",
    "type": "text",
    "body": "..."
  }
}

4. Select the next integration task

• Register a business capability when the agent needs

data or an action from the host application.

• Read authentication before handling 401 responses or storing the

key in deployment configuration.

• Read environments before promoting an integration beyond

development.

Troubleshooting

| Response | Meaning | Next action |

|---|---|---|

| `401` | The API key is missing, invalid, expired, revoked, or unavailable for this environment. | Ask the Forgium administrator for a replacement. |

| `422` | The request body is invalid. | Send a `message` with `type: "text"` and a non-empty `body`. |

| `500` | The agent runtime could not complete the request. | Retry only if the host application's retry policy allows it; retain the response details and contact the operator if it persists. |

The OpenAPI contract is authoritative for all request and

response fields.