> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Resolve config for a session > 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. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/agent-config/{key}/resolve openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Autoimprove - name: Agent Config - name: Knowledge Base - name: Config - name: CLI Auth - name: Call Analysis - name: Benchmark - name: Health paths: /v1/agent-config/{key}/resolve: post: tags: - Agent Config summary: Resolve config for a session description: >- 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. operationId: postV1Agent-configByKeyResolve parameters: - in: path name: key schema: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$ minLength: 1 maxLength: 120 required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/ResolveManagedConfigRequest' responses: '200': description: The resolved config for this session. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ResolveManagedConfigResponse' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Unknown key and no defaults were provided '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: |- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.agentConfig.resolve('x'); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.agent_config.resolve( key="x", ) print(response.data) components: schemas: ResolveManagedConfigRequest: type: object properties: defaults: type: object additionalProperties: {} description: >- 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. example: systemPrompt: You are a helpful receptionist. model: gpt-4.1 temperature: 0.4 session: type: object properties: sessionId: type: string maxLength: 255 description: Your session or room identifier, for correlation. callerNumber: type: string maxLength: 32 description: >- The number calling your agent (E.164). Required for simulation recognition. example: '+15551230000' calledNumber: type: string maxLength: 32 description: The number your agent was reached on (E.164). example: '+15559870000' description: >- 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. ResolveManagedConfigResponse: type: object properties: key: type: string channel: type: string enum: - production - staging description: Which channel this session resolved to. revisionId: type: string format: uuid document: type: object additionalProperties: {} description: The config JSON to apply. simulationJobId: type: - string - 'null' format: uuid description: >- Set when this session is a Roark simulation call. Stamp it (and the revisionId) into your session metadata so analysis attributes the call correctly. required: - key - channel - revisionId - document - simulationJobId ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````