---
title: "Resolve config for a session"
method: POST
path: "/v1/agent-config/{key}/resolve"
tags: ["Agent Config"]
---

# Resolve config for a session

`POST /v1/agent-config/{key}/resolve`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/agent-config/{key}/resolve`
- Auth: HTTP bearer

The call your agent makes at session start. Returns the config JSON for this session, with per-session simulation recognition built in: when the session was originated by a Roark simulation (matched by caller number against the calls Roark has in flight), the STAGING revision is served for that session only, so Autoimprove candidates are tested on your real deployment. Real traffic always resolves to production; any recognition miss degrades to production too.

On the first fetch of an unknown key, pass `defaults` (your baked-in config): the key is registered and the defaults become revision 1. That makes integration a single call.

Cache the response per session; do not fetch per turn.

## Path parameters

- `key` string, required

## Request body

- ResolveManagedConfigRequest
  - `defaults` object: Your baked-in config. On the first fetch of an unknown key this registers the config and becomes revision 1, so integration is a single call. Ignored once the key exists.
  - `session` object: Session context. When the call was originated by a Roark simulation, Roark recognizes it here and serves the staging revision for this session only; real traffic always gets production.
    - `sessionId` string: Your session or room identifier, for correlation.
    - `callerNumber` string: The number calling your agent (E.164). Required for simulation recognition.
    - `calledNumber` string: The number your agent was reached on (E.164).

## Response `200`

The resolved config for this session.

- object
  - `data` ResolveManagedConfigResponse, required
    - `key` string, required
    - `channel` 'production' | 'staging', required: Which channel this session resolved to.
    - `revisionId` string, uuid, required
    - `document` object, required: The config JSON to apply.
    - `simulationJobId` string, uuid, nullable, required: Set when this session is a Roark simulation call. Stamp it (and the revisionId) into your session metadata so analysis attributes the call correctly.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Unknown key and no defaults were provided
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-09-22** `29256c5296cf`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/agent-config/:key/resolve/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)