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

Request the access bundle from the Forgium administrator

for the target environment. It contains:

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

If either value is unavailable, stop here and use Request access.

Do not substitute a guessed host, placeholder URL, or another environment's key.

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.

This is the completion evidence for a connectivity-only test. 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. If an agent cannot locate the contract, use the exact commands

in Contract retrieval; do not substitute another

contract. For staging or production, validate the bundle and environment

isolation described in Environments.

For a server-side adapter pattern, error mapping, conversation handling, and

production security checklist, see HTTP integration reference.