> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create an agent with an External App, make it ready to run, publish a workflow that uses it, then dispatch and read the run with curl or a Next.js route on Vercel.

This quickstart covers the complete integration path: credential, agent, readiness, workflow, durable run, and readback.
Pick the tab for your stack:

* **Console walkthrough** uses Console for workflow authoring and HTTP API v3 for integration. Start here if this is your first run; the other tabs dispatch the workflow it publishes.
* **Raw HTTP** walks the API from any HTTP client, with `curl` examples.
* **Next.js** calls Forge from a Next.js server route and deploys it to Vercel.

An AI host such as Claude Code uses the [MCP host quickstart](https://docs.gloo.com/forge/quickstart/mcp-host.md) instead.

> [tab] Console walkthrough
>
> ### Prerequisites
>
> You need Console access for agent setup and workflow authoring, an External App owned by an org unit, and `curl` plus `jq`. Use a deployment with an available inference provider and a model your agent can use. Creating an agent is reserved for External App credentials. See [Access and credentials](https://docs.gloo.com/forge/get-started/credentials-and-access.md) before continuing if you do not have these.
>
> ### 1. Prepare a caller
>
> In Console, register an External App owned by an org unit, and give it roles holding `agents:read`,
> `agents:write`, `workflows:use` and `runs:read`, plus `switches:use` at platform scope for the
> activation in step 3. Of the system roles, only **Platform admin** holds `switches:use`. Request matching token scopes; scopes only narrow the app's role grants. See
> [Access and credentials](https://docs.gloo.com/forge/get-started/credentials-and-access.md).
>
> ```bash theme={null}
> export FORGE_BASE="https://api.forge.gloo.com"
> export FORGE_CLIENT_ID="<client-id>"
> export FORGE_CLIENT_SECRET="<client-secret>"
> ACCESS_TOKEN=$(curl -fsS -X POST "$FORGE_BASE/oauth/token" \
>   -H "Content-Type: application/x-www-form-urlencoded" \
>   -d "grant_type=client_credentials" \
>   -d "client_id=$FORGE_CLIENT_ID" \
>   -d "client_secret=$FORGE_CLIENT_SECRET" \
>   -d "scope=agents:read agents:write switches:use workflows:use runs:read" | jq -er .access_token)
> ```
>
> Store the secret server-side and renew the token before its `expires_in` lifetime ends. The granted permissions can be narrower than the requested scopes.
>
> ### 2. Create the agent
>
> Send JSON with bearer auth to `POST /api/v3/agents`. Use a stable agent identifier and idempotency key for this creation intent:
>
> ```bash theme={null}
> curl -fsS -X POST "$FORGE_BASE/api/v3/agents" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: <stable-create-intent-key>" \
>   -d '{"agentId":"demo-summariser","name":"Demo Summariser","description":"Summarises text","prompt":{"core":"Reply in two short sentences."},"model":{"default":"anthropic/claude-haiku-4-5"}}'
> ```
>
> With no `status`, the agent is created as a draft, homed at the app's owning org unit.
>
> ### 3. Activate the agent
>
> ```bash theme={null}
> curl -fsS -X PATCH "$FORGE_BASE/api/v3/agents/demo-summariser" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: <stable-activate-intent-key>" \
>   -d '{"status":"active"}'
> ```
>
> Activating gives the agent the worker that runs its workflow steps. A status change is an operator control: without `switches:use` at the platform the request is `403 forbidden` and nothing changes. Active status does not bypass readiness, permissions, tool credentials, or governance checks at dispatch.
>
> ### 4. Finish the agent's setup in Console
>
> An agent created by an org-unit-owned External App has no owner, sits in no position, and has no attested identity, so the runtime refuses to give it work until a person finishes its setup. Open **Workforce → Agents**, select **Demo Summariser**, and on its **Overview** tab work through **Ready to run** until the status reads **Ready**:
>
> 1. **Choose a position** places the agent in a vacant position an agent can hold, or **Create a position** makes one. **Choose a Job** then gives that position its Job.
> 2. **Assign owner** names the person who answers for the agent; then **Acknowledge review** if the checklist asks for it.
> 3. **Attest identity** confirms the owner and the agent's current definition.
> 4. **Give Access** appears only if the agent lacks the Access its steps need.
>
> Each fix names the permission it needs; without it, **Request setup** sends the gaps to people who hold it. See [Check that an agent is ready to run](https://docs.gloo.com/forge/console/workforce/agents#check-that-an-agent-is-ready-to-run).
>
> ### 5. Publish a workflow in Console
>
> In Console, open **Production → Workflows** and create a workflow. The builder names a new workflow
> `untitled-workflow-<timestamp>`; click the name and rename it `summarise-input`, because the dispatch
> calls below find the workflow by that name. Then:
>
> 1. Add a required workflow input named `text` with type `string`.
> 2. Add an **Agent** step named `summarise`.
> 3. Set **Assigned to → AI** and select **Demo Summariser**. The picker shows each agent's readiness; it should read **Ready**.
> 4. In the step's **Prompt**, write `Summarise this text: {{workflow.text}}`. A new Agent step declares no inputs, so there is nothing to bind: `{{workflow.text}}` reads the run's `text` argument directly. See [Reference a workflow input from inside a node](https://docs.gloo.com/forge/build/compose-a-workflow.md#reference-a-workflow-input-from-inside-a-node).
> 5. In the step's **Properties** panel, add an output named `summary` under **Outputs**; a new output is a `string`. Leave the step's **Validation Strategy** on **Schema**, its starting value. `summarise` is the last step, so its `summary` becomes the workflow's output; the builder has no separate workflow-output editor. See [Declare step and workflow outputs](https://docs.gloo.com/forge/console/production/workflows/step-settings.md#declare-step-and-workflow-outputs). Then publish the draft and record its active version.
>
> If the publish check reports a missing agent, worker, owner, output, or permission, fix that gate rather
> than overriding it. Programmatic authoring is documented under the generated workflow operations;
> MCP hosts can use `forge_ask_workflow_architect` to propose and revise a draft.
>
> ### 6. Dispatch one logical intent
>
> Choose an explicit `Idempotency-Key` for this logical dispatch intent. Keep that key if a timeout leaves the outcome unknown; use a new key only for a deliberately new run.
>
> ```bash theme={null}
> curl -fsS -X POST "$FORGE_BASE/api/v3/workflows/dispatch" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: <stable-dispatch-intent-key>" \
>   -d '{"name":"summarise-input","runtimeArgs":{"text":"Summarise this text."}}' | jq '{data,meta}'
> ```
>
> The response uses `{data,meta}` and includes `meta.requestId`. For a failed or unknown mutation outcome, [reconcile the authorized resource state](https://docs.gloo.com/forge/reference/idempotency.md) before deciding whether another effect is appropriate.
>
> ### 7. Inspect the run
>
> Copy `data.runId` from the dispatch response. Open that run in Console to inspect status, holds, evidence, and output. For a direct read:
>
> ```bash theme={null}
> RUN_ID="<runId-from-dispatch>"
> curl -fsS "$FORGE_BASE/api/v3/runs/$RUN_ID" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" | jq '{data,meta}'
> ```
>
> A successful dispatch means a run was accepted; it does not mean the work completed. Check the returned run status and any hold or failure before using its output. For paginated run history, follow `meta.nextCursor` while `meta.hasMore` is true.
>
> Read the [HTTP conventions](https://docs.gloo.com/forge/reference/conventions.md) and [errors](https://docs.gloo.com/forge/reference/errors.md) pages for response metadata, denial handling, and retries.

> [tab] Raw HTTP
>
> ### Raw HTTP
>
> The contract is the same in every language: OAuth2 client credentials, then a bearer token, then JSON over `/api/v3`. Each resource is a collection (`/api/v3/agents`), each record is its id in the path (`/api/v3/agents/{agentId}`), and the HTTP method is the verb. Every v3 route runs the same operation as its `/api/v2` route, with the same permissions and responses; v2 is unchanged. The response envelope, error format, and pagination behavior are documented in the [API reference](https://docs.gloo.com/forge/reference.md).
>
> #### Prerequisites
>
> * Forge's API host: `https://api.forge.gloo.com` in production. For staging, use your staging deployment's `*.convex.site` origin; the purpose host `https://api.forge.staging.gloo.us` is pending DNS, certificate verification and activation. See [Conventions → Base URL](https://docs.gloo.com/forge/reference/conventions.md#base-url).
>
> * An External App registered in Forge from **Platform → Developers → External Apps** in the Forge Console, owned by an org unit. Creating an agent homes it at the app's owning org unit, so an app owned by a user, factory or project cannot create one.
>
> * Roles given to that app. External Apps are default-deny: a new app holds no roles, so it can mint a token but every call below answers `403`. Open the app, and under **Roles** choose **Manage roles** (you need `grants:manage`). Give roles holding `agents:read`, `agents:write`, `workflows:use` and `runs:read`, at platform scope or at the organization that **Manage roles** names, and `switches:use` at platform scope to activate the agent (only the **Platform admin** role holds it). See [External Apps → Roles and scopes](https://docs.gloo.com/forge/console/platform/external-apps#roles-and-scopes). Token scopes only narrow these roles; they grant nothing on their own.
>
> * `curl` and `jq`, or any HTTP client with JSON support.
>
> > [!TIP]
> >
> > Calling the API yourself rather than from software that must outlive you? A [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#use-a-key) (`fmcp_…`) is sent directly as the bearer, with no token mint. Creating and updating an agent is reserved for External Apps and refuses it; every other step below accepts the key in place of `$ACCESS_TOKEN`. See [Choose a credential](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential).
>
> **1. Set environment variables**
>
> ```bash theme={null}
> export FORGE_BASE="https://api.forge.gloo.com"
> export FORGE_CLIENT_ID="<client-id>"
> export FORGE_CLIENT_SECRET="<client-secret>"
> ```
>
> **2. Mint a bearer token**
>
> ```bash theme={null}
> ACCESS_TOKEN=$(curl -sS -X POST "$FORGE_BASE/oauth/token" \
>   -H "Content-Type: application/x-www-form-urlencoded" \
>   -d "grant_type=client_credentials" \
>   -d "client_id=$FORGE_CLIENT_ID" \
>   -d "client_secret=$FORGE_CLIENT_SECRET" \
>   -d "scope=agents:read agents:write switches:use workflows:use runs:read" \
>   | jq -er .access_token)
> ```
>
> The token response declares its lifetime in `expires_in`. Renew before that lifetime ends; do not assume a fixed duration or print the token into logs.
>
> **3. Smoke test: list agents**
>
> ```bash theme={null}
> curl -sS "$FORGE_BASE/api/v3/agents" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   | jq '.data[] | {agentId, name, status}'
> ```
>
> Every list endpoint returns `{ data: [...], meta: { requestId, hasMore?, nextCursor? } }`. Keep the `requestId` in your logs; it is the audit-trail key for support requests.
>
> **4. Create an agent**
>
> ```bash theme={null}
> curl -sS -X POST "$FORGE_BASE/api/v3/agents" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: demo-agent-create-v1" \
>   -d '{
>     "agentId": "demo-summariser",
>     "name": "Demo Summariser",
>     "description": "Summarises a block of text in 2-3 sentences.",
>     "prompt": { "core": "You are a concise summariser. Reply with 2-3 short sentences. No preamble." },
>     "model": { "default": "anthropic/claude-haiku-4-5" }
>   }' | jq .
> ```
>
> The body is strict: an unknown field is `400 bad_request`. The allowed fields are `agentId`, `name`, `description`, `purpose`, `status`, `tags`, `model` and `prompt`; see [`CreateAgentBody`](https://docs.gloo.com/forge/reference/http-api/agents/create). `status` is `draft` (the default) or `active`; this agent is a draft until the next step activates it. The response includes `data.id`, `data.agentId`, and request metadata in `meta`.
>
> **5. Activate the agent**
>
> ```bash theme={null}
> curl -sS -X PATCH "$FORGE_BASE/api/v3/agents/demo-summariser" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: demo-agent-activate-v1" \
>   -d '{ "status": "active" }' | jq .
> ```
>
> The path names the agent by its slug (`agentId`), so the body carries only the fields that change. Activating gives the agent the worker that runs its workflow steps. A patch that carries a `status` (`draft`, `active`, `paused` or `deprecated`) is an operator control: it also needs `switches:use` at the platform, and without it the request is `403 forbidden` and nothing is written.
>
> **6. Dispatch a workflow**
>
> Finish the agent's setup and publish the `summarise-input` workflow before dispatching. [`GET /api/v3/agents/demo-summariser/readiness`](https://docs.gloo.com/forge/reference/http-api/agents/getReadiness) lists each check by `id`, and a check with `blocksDispatch: true` stops dispatch until it passes. Clear each failing check over HTTP, or in Console ([step 4 of the Console walkthrough](https://docs.gloo.com/forge/quickstart.md#4-finish-the-agent’s-setup-in-console)):
>
> | Check | How to clear it |
> | - | - |
> | `worker_seated` | Find the agent's worker (`GET /api/v3/workers?workerType=AGENT`; it carries the agent's name) and a vacant position an agent can hold (`GET /api/v3/positions`). Then [seat the worker](https://docs.gloo.com/forge/reference/http-api/workforce/createPositionAssignment.md) with `POST /api/v3/positions/{positionId}/assignments` and the body `{ "workerId": "<worker id>", "assignmentKind": "PRIMARY", "startDate": <epoch ms>, "reason": "Seat Demo Summariser" }`. This needs `org:manage` and `workforce:read` at the platform scope. Seating the worker also clears `owner_traceable`. |
> | `position_has_job` | Set the Job through an org chart draft. [Open a draft](https://docs.gloo.com/forge/reference/http-api/org-units-positions/admin/drafts-create.md) with `POST /api/v3/org-unit-drafts` (its id is in `data`). [Stage the Job](https://docs.gloo.com/forge/reference/http-api/org-units-positions/admin/drafts-positions-update.md) with `PATCH /api/v3/org-unit-drafts/{draftId}/positions/{positionId}` and the body `{ "workerRoleId": "<job role id>" }`. Then [publish the draft](https://docs.gloo.com/forge/reference/http-api/org-units-positions/admin/drafts-publish.md) with `POST /api/v3/org-unit-drafts/{draftId}/publish`. These need `org:manage` and a Personal key or platform API key; an External App cannot call them. In Console, use **Choose a Job** on the agent's [Ready to run](https://docs.gloo.com/forge/console/workforce/agents#check-that-an-agent-is-ready-to-run) checklist. |
> | `owner_present` | [Assign the owner](https://docs.gloo.com/forge/reference/http-api/agents/assignOwner.md) with `POST /api/v3/agents/demo-summariser/assign-owner` and the body `{ "ownerPersonId": "<person id>" }`. This also starts a new 90-day review window. |
> | `owner_review_current` | [Acknowledge the review](https://docs.gloo.com/forge/reference/http-api/agents/acknowledgeReview.md) with `POST /api/v3/agents/demo-summariser/acknowledge-review` and the body `{}`. |
> | `identity_attested` | [Attest the identity](https://docs.gloo.com/forge/reference/http-api/agents/attestIdentity.md) with `POST /api/v3/agents/demo-summariser/attest-identity`. Only a person can attest, so send that person's [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#use-a-key) as the bearer; an External App is refused with `403`. |
> | `access_floor` | [Give the agent a role](https://docs.gloo.com/forge/reference/http-api/governance/giveRole.md) with `POST /api/v3/governance-holders/{agent id}/roles` and the body `{ "actorKind": "agent", "roleKey": "agent_worker", "orgUnitId": "<company org unit id>" }`. The agent id is the `data.id` from the create call, and `orgUnitId` is the root org unit of the agent's company. This needs `grants:manage` at your acting organization and where the grant is, and you must hold every permission in `agent_worker` there. In Console, the same fix is **Give Access**. |
>
> The owner, review and identity routes need `agents:manage` at the agent's home org unit. Binding the agent to a draft node needs Console ([step 5](https://docs.gloo.com/forge/quickstart.md#5-publish-a-workflow-in-console)), because the v3 draft node config has no agent field, or the Workflow Architect described below.
>
> > [!TIP]
> >
> > To build and publish a workflow with no Console at all, use the Workflow Architect over HTTP with a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#use-a-key): `POST /api/v3/workflows/start-architect-conversation`, then poll `GET /api/v3/workflows/{workflowId}/architect-messages` until the turn is idle, check `GET /api/v3/workflows/{workflowId}/draft-validation`, and publish with `POST /api/v3/workflows/{workflowId}/publish-draft`. An External App cannot start the conversation. See [Start a Workflow Architect conversation](https://docs.gloo.com/forge/reference/http-api/workflows/startArchitectConversation.md).
>
> The workflow's required input is `text`. This request starts the published definition:
>
> ```bash theme={null}
> RUN_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/workflows/dispatch" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: demo-summarise-run-v1" \
>   -d '{
>     "name": "summarise-input",
>     "runtimeArgs": { "text": "Convex is a TypeScript backend with reactive queries and durable workflows. Forge stacks orchestration and governance on top." }
>   }' | jq -er .data.runId)
>
> echo "Run started: $RUN_ID"
> ```
>
> **7. Poll the run**
>
> ```bash theme={null}
> curl -sS "$FORGE_BASE/api/v3/runs/$RUN_ID" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   | jq '.data | {status, startedAt, completedAt, outputs}'
> ```
>
> A run reports one of six statuses: `running`, `paused`, `cancellation_requested`, `completed`,
> `failed` or `cancelled`. There is no queued status; a run is `running` from the moment it starts,
> including while a step waits for a person or a policy decision. `paused` appears when someone
> pauses a delegated run. Treat the returned status as the contract rather than assuming a fixed
> linear sequence. Forge runs are durable, so you can fetch a run minutes or hours later.
>
> **8. Handle errors**
>
> Every error response is `{ error: { code, message, details? }, meta: { requestId } }`. Inspect the `code` to branch:
>
> ```bash theme={null}
> RESP=$(curl -sS -w "\n%{http_code}" "$FORGE_BASE/api/v3/agents/does-not-exist" \
>   -H "Authorization: Bearer $ACCESS_TOKEN")
> BODY=$(echo "$RESP" | sed '$d')
> STATUS=$(echo "$RESP" | tail -n 1)
>
> if [ "$STATUS" -ne 200 ]; then
>   CODE=$(echo "$BODY" | jq -r .error.code)
>   echo "Error: $CODE — see /forge/reference/errors"
> fi
> ```
>
> The full error code list is in [Errors](https://docs.gloo.com/forge/reference/errors.md). For event-driven updates instead of polling, configure [webhooks](https://docs.gloo.com/forge/run/webhooks.md) for the events your integration owns.

> [tab] Next.js
>
> ### Next.js
>
> Use a Next.js server route for Forge calls so the External App client secret and bearer stay on the server. Create the agent and publish the `summarise-input` workflow from [steps 2 to 5 of the Console walkthrough](https://docs.gloo.com/forge/quickstart.md#2-create-the-agent) first.
>
> #### Configure the server
>
> Set `FORGE_API_URL` to `https://api.forge.gloo.com` in production, or your staging deployment's `*.convex.site` origin for staging, and store `FORGE_CLIENT_ID` and `FORGE_CLIENT_SECRET` as server-only environment variables. Grant the External App only the permissions its routes need. The staging purpose host `https://api.forge.staging.gloo.us` is pending DNS, certificate verification and activation; see [staging availability](https://docs.gloo.com/forge/reference/conventions.md#base-url).
>
> ```typescript theme={null}
> async function mintForgeToken(): Promise<string> {
>   const baseUrl = process.env.FORGE_API_URL;
>   const clientId = process.env.FORGE_CLIENT_ID;
>   const clientSecret = process.env.FORGE_CLIENT_SECRET;
>   if (!baseUrl || !clientId || !clientSecret) throw new Error("Forge server configuration is missing");
>
>   const body = new URLSearchParams({
>     grant_type: "client_credentials",
>     client_id: clientId,
>     client_secret: clientSecret,
>     scope: "workflows:use runs:read",
>   });
>   const response = await fetch(new URL("/oauth/token", baseUrl), {
>     method: "POST",
>     headers: { "Content-Type": "application/x-www-form-urlencoded" },
>     body,
>     cache: "no-store",
>   });
>   if (!response.ok) throw new Error("Forge token request failed: " + response.status);
>   const token = (await response.json()) as { access_token: string };
>   return token.access_token;
> }
> ```
>
> #### Dispatch from a server route
>
> Give each user intent a stable key. Persist it in your own request or job record so a timeout can be reconciled without minting a second logical operation.
>
> ```typescript theme={null}
> export async function POST(request: Request): Promise<Response> {
>   const baseUrl = process.env.FORGE_API_URL;
>   if (!baseUrl) return Response.json({ error: "Forge server configuration is missing" }, { status: 500 });
>   const { text, intentKey } = (await request.json()) as { text: string; intentKey: string };
>   if (!text || !intentKey) return Response.json({ error: "text and intentKey required" }, { status: 400 });
>
>   const bearer = await mintForgeToken();
>   const response = await fetch(new URL("/api/v3/workflows/dispatch", baseUrl), {
>     method: "POST",
>     headers: {
>       Authorization: "Bearer " + bearer,
>       "Content-Type": "application/json",
>       "Idempotency-Key": intentKey,
>     },
>     body: JSON.stringify({ name: "summarise-input", runtimeArgs: { text } }),
>     cache: "no-store",
>   });
>   if (!(response.headers.get("Content-Type") ?? "").includes("application/json")) {
>     // A gateway failure can be HTML; never forward it. The outcome is unknown, so keep intentKey.
>     return Response.json({ error: "Forge dispatch outcome unknown", intentKey }, { status: 502 });
>   }
>   const envelope = await response.json();
>   return Response.json(envelope, { status: response.status });
> }
> ```
>
> Keep secrets out of browser bundles and logs. The response is `{data,meta}` or `{error,meta}` for application responses; a gateway can return non-JSON. Preserve `meta.requestId` for support. On an unknown write outcome, [reconcile state first](https://docs.gloo.com/forge/reference/idempotency.md). Read run status through [the HTTP runs operations](https://docs.gloo.com/forge/reference/http-api/runs).
>
> #### Deploy to Vercel
>
> The same route deploys to Vercel. The production checklist is environment variables, runtime selection, and token renewal.
>
> 1. **Add the environment variables.** In the Vercel dashboard, open **Project → Settings → Environment Variables** and add them to **Production**, and to **Preview** if preview deployments should call Forge:
>
>    | Name | Value | Scope |
>    | - | - | - |
>    | `FORGE_API_URL` | `https://api.forge.gloo.com` | All environments |
>    | `FORGE_CLIENT_ID` | Your External App client ID | Production, Preview |
>    | `FORGE_CLIENT_SECRET` | Your External App secret | Production, Preview (Sensitive) |
>
>    Mark `FORGE_CLIENT_SECRET` as sensitive. Or use the CLI:
>
>    ```bash theme={null}
>    vercel env add FORGE_API_URL production
>    vercel env add FORGE_CLIENT_ID production
>    vercel env add FORGE_CLIENT_SECRET production --sensitive
>    ```
>
>    Redeploy after adding them; environment variables take effect only on new deployments.
>
> 2. **Pick the runtime.** Native Forge HTTP calls work in both the Node and Edge runtimes. Choose from your application's supported dependencies and measured deployment behavior. A module-local token cache is per-instance and non-durable in either runtime, so every instance must be able to mint a fresh token before the current one expires. To opt a route into Edge, add `export const runtime = "edge";` to the route file and drop any `import "server-only"` from the helper. Never mint a runtime bearer at build time; it is short-lived.
>
> 3. **Verify the deployment.** Call the route from the deployed origin, then open **Production → Runs** in Console. The run shows the deployment's External App as the dispatching principal.
>
>    ```bash theme={null}
>    curl -X POST https://your-app.vercel.app/api/summarise \
>      -H "Content-Type: application/json" \
>      -d '{"text":"hello world","intentKey":"demo-intent-1"}'
>    ```
>
> 4. **Correlate logs.** Log `meta.requestId` from every Forge response in your structured logs so a failure cross-references the Forge audit trail. For alerting on run state, subscribe to [webhooks](https://docs.gloo.com/forge/run/webhooks.md) or list runs with a status filter.
>
> A hosted Forge deployment needs no Convex link in your Vercel project; `FORGE_API_URL` is all the route uses.
>
> If the call fails:
>
> * **401 from Forge:** verify the client id and secret, app activation, token expiry, API origin, and bearer header; then mint a fresh token.
> * **403 from Forge:** preserve `meta.requestId`, then check the required permission, the app's role-grant scope, resource reach, and the scopes requested when minting the token.
> * **Timeout or non-JSON gateway response:** keep the logical `Idempotency-Key` and treat a write outcome as unknown. Reconcile the resource before deciding whether another effect is appropriate.
> * **`FORGE_CLIENT_SECRET` is undefined:** the variable is not set for this environment. Check its scope and redeploy.

## Next steps

* [HTTP conventions](https://docs.gloo.com/forge/reference/conventions.md), [errors](https://docs.gloo.com/forge/reference/errors.md), and [idempotency](https://docs.gloo.com/forge/reference/idempotency.md) for response metadata, denial handling, and retries.
* [Choose an interface](https://docs.gloo.com/forge/get-started/choose-an-interface.md) to compare Console, HTTP API v3, and MCP.
* [MCP host quickstart](https://docs.gloo.com/forge/quickstart/mcp-host.md) to use Forge as tools inside an AI host.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.