> ## Documentation Index > Fetch the complete documentation index at: https://allhandsai-chore-regenerate-agent-sdk-openapi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Initialize Server > Initialize a dormant server with runtime configuration. Returns 400 if the server has already been initialized (state != dormant). Returns 500 if initialization fails; in that case the state rolls back to ``dormant`` so the orchestrator can retry. ## OpenAPI ````yaml /openapi/agent-sdk.json post /api/init openapi: 3.1.0 info: description: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent title: OpenHands Agent Server version: 1.52.0 servers: [] security: [] paths: /api/init: post: tags: - Init summary: Initialize Server description: >- Initialize a dormant server with runtime configuration. Returns 400 if the server has already been initialized (state != dormant). Returns 500 if initialization fails; in that case the state rolls back to ``dormant`` so the orchestrator can retry. operationId: initialize_server_api_init_post requestBody: content: application/json: schema: $ref: '#/components/schemas/InitRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/InitStatus' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - APIKeyHeader: [] components: schemas: InitRequest: additionalProperties: false description: >- Runtime configuration delivered at /api/init time. Each field is optional and overrides the equivalent field on the dormant ``Config``. Fields not provided keep the value the server was constructed with (typically from env vars at pod startup). The set of overridable fields is intentionally narrow — it covers the values that today are "env-var shaped" and must change per-user, not image-build-time configuration (Python deps, plugin set, etc.) which stays bound to the warm-pool flavor. properties: allow_cors_origins: anyOf: - items: type: string type: array - type: 'null' description: CORS origins to add to the existing localhost allowlist. title: Allow Cors Origins bash_events_dir: anyOf: - format: path type: string - type: 'null' description: >- Directory where bash events are persisted. Typically located inside the mounted user workspace. title: Bash Events Dir conversation_worktree_root: anyOf: - format: path type: string - type: 'null' description: >- Root directory for conversation git worktrees. Override this to point at the mounted user workspace. title: Conversation Worktree Root conversations_path: anyOf: - format: path type: string - type: 'null' description: >- Directory where conversations are persisted. Override this to point at the mounted user workspace. title: Conversations Path env: anyOf: - additionalProperties: type: string type: object - type: 'null' description: >- Process environment variables to set before conversation services start. Useful for credentials consumed by tools (e.g. GITHUB_TOKEN). These are applied with ``os.environ.update``; existing values are overwritten. title: Env max_concurrent_runs: anyOf: - minimum: 1 type: integer - type: 'null' description: Override the conversation-step concurrency limit. title: Max Concurrent Runs secret_key: anyOf: - format: password type: string writeOnly: true - type: 'null' description: >- Symmetric secret used to encrypt persisted secrets. If not provided, falls back to the first session_api_key (matching the default Config behavior). title: Secret Key session_api_keys: anyOf: - items: type: string type: array - type: 'null' description: >- Per-user session API keys. If provided, all subsequent /api/* requests must authenticate with one of these keys via the X-Session-API-Key header. title: Session Api Keys telemetry: anyOf: - $ref: '#/components/schemas/TelemetrySpec' - type: 'null' description: >- Product-analytics policy for this pod. Without this, a warm-pool pod keeps whatever mode it booted with (normally 'disabled'), so a deployment that expects telemetry must supply it here. web_url: anyOf: - type: string - type: 'null' description: >- External URL where this server is reachable, used for root-path calculation. Only honored when not already set in dormant config. title: Web Url webhooks: anyOf: - items: $ref: '#/components/schemas/WebhookSpec' type: array - type: 'null' description: Per-user webhooks (e.g. for streaming events back). title: Webhooks title: InitRequest type: object InitStatus: properties: error: anyOf: - type: string - type: 'null' description: >- If a previous /api/init attempt failed, the error message. The state rolls back to ``dormant`` so /api/init can be retried. title: Error state: description: >- ``dormant`` — server is up but waiting for /api/init. ``initializing`` — /api/init has been received and services are starting. ``ready`` — initialization complete; all /api/* routes are live. enum: - dormant - initializing - ready title: State type: string required: - state title: InitStatus type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object TelemetrySpec: description: |- Deployment-supplied product-analytics transport settings. This carries transport plus the non-identifying deployment tag. Whether telemetry may be delivered is resolved from consent (``misc_settings.telemetry.consent``, optionally seeded or overridden by ``OH_TELEMETRY_CONSENT``). properties: deployment_kind: default: local description: >- Deployment kind attached to diagnostic events. Use 'remote' for hosted OpenHands and 'local' for self-hosted or developer runs. enum: - local - remote title: Deployment Kind type: string event_buffer_size: default: 20 description: Maximum events per delivery batch. minimum: 1 title: Event Buffer Size type: integer exporter: default: none description: >- Exporter to use. 'none' (the default) never delivers, and is what library and headless consumers get. 'posthog' requires the [posthog] extra. 'http' POSTs sanitized batches to telemetry_http_endpoint. enum: - none - posthog - http title: Exporter type: string flush_delay: default: 30 description: Seconds to wait before flushing a partial batch. exclusiveMinimum: 0 title: Flush Delay type: number http_endpoint: anyOf: - type: string - type: 'null' description: >- Endpoint the 'http' exporter POSTs sanitized event batches to. Intended to front a backend that revalidates auth and consent before forwarding onward. title: Http Endpoint http_token: anyOf: - format: password type: string writeOnly: true - type: 'null' description: Bearer token sent by the 'http' exporter, if required. title: Http Token max_queue_size: default: 1000 description: >- Upper bound on buffered diagnostic events. The queue is bounded on ingest: past this many events the oldest are dropped, so a failing exporter cannot grow memory without limit. minimum: 1 title: Max Queue Size type: integer num_retries: default: 2 description: Retries before a batch is dropped. minimum: 0 title: Num Retries type: integer posthog_api_key: anyOf: - format: password type: string writeOnly: true - type: 'null' description: >- PostHog project API key. Required by the 'posthog' exporter; without it telemetry stays inactive. title: Posthog Api Key posthog_host: default: https://us.i.posthog.com description: PostHog ingestion host. title: Posthog Host type: string retry_delay: default: 5 description: Base seconds between delivery retries. minimum: 0 title: Retry Delay type: number salt: anyOf: - format: password type: string writeOnly: true - type: 'null' description: >- Key used to pseudonymize conversation identifiers. Falls back to a per-process random salt, which keeps pseudonyms stable within a run but unlinkable across runs. title: Salt title: TelemetrySpec type: object WebhookSpec: description: Spec to create a webhook. All webhook requests use POST method. properties: base_url: description: >- The base URL of the webhook service. Events will be sent to {base_url}/events and conversation info to {base_url}/conversations title: Base Url type: string event_buffer_size: default: 5 description: The number of events to buffer locally before posting to the webhook minimum: 1 title: Event Buffer Size type: integer flush_delay: default: 30 description: >- The delay in seconds after which buffered events will be flushed to the webhook, even if the buffer is not full. Timer is reset on each new event. exclusiveMinimum: 0 title: Flush Delay type: number headers: additionalProperties: type: string title: Headers type: object max_batch_bytes: default: 5242880 description: >- Upper bound on the serialized size of each webhook request. A single event larger than this limit is sent by itself. minimum: 1 title: Max Batch Bytes type: integer max_queue_bytes: default: 52428800 description: >- Upper bound on the serialized size of events buffered for delivery. The oldest events are dropped when the queue exceeds this bound. minimum: 1 title: Max Queue Bytes type: integer max_queue_size: default: 1000 description: >- Upper bound on the number of events buffered for delivery. The oldest events are dropped past this bound to prevent unbounded memory growth. minimum: 1 title: Max Queue Size type: integer num_retries: default: 3 description: The number of times to retry if the post operation fails minimum: 0 title: Num Retries type: integer retry_delay: default: 5 description: The delay between retries minimum: 0 title: Retry Delay type: integer required: - base_url title: WebhookSpec type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object securitySchemes: APIKeyHeader: in: header name: X-Session-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.