> ## Documentation Index > Fetch the complete documentation index at: https://docs.archal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create environments with optional initial state ## OpenAPI ````yaml /api-reference/openapi.json post /api/sessions openapi: 3.1.0 info: title: Archal API version: 1.0.0 summary: >- Stateful testing environments with separate lifecycle and provider-scoped credentials description: >- Use a workspace credential for lifecycle operations. Each created environment returns a short-lived provider-shaped credential for its isolated data plane; the workspace credential is never forwarded to or accepted by provider-compatible endpoints. servers: - url: https://api.archal.ai security: [] paths: /api/sessions: post: summary: Create environments with optional initial state operationId: createEnvironmentSession parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 200 requestBody: required: true content: application/json: schema: type: object properties: ttlSeconds: type: integer minimum: 1 maximum: 14400 initialState: type: object propertyNames: type: string minLength: 1 maxLength: 80 additionalProperties: oneOf: - type: object properties: format: type: string const: json value: type: object propertyNames: type: string additionalProperties: {} required: - format - value additionalProperties: false - type: object properties: format: type: string const: sql value: type: string minLength: 1 required: - format - value additionalProperties: false environments: minItems: 1 type: array items: type: string minLength: 1 maxLength: 80 required: - environments additionalProperties: false responses: '201': description: Environment session created content: application/json: schema: type: object properties: sessionId: type: string minLength: 1 status: type: string enum: - starting - ready - running - tearing_down - ended - expired - failed environmentIds: minItems: 1 type: array items: type: string minLength: 1 maxLength: 80 environments: type: object propertyNames: type: string minLength: 1 maxLength: 80 additionalProperties: oneOf: - type: object properties: status: type: string const: ready apiBaseUrl: type: string format: uri mcpUrl: anyOf: - type: string format: uri - type: 'null' credentials: type: object properties: kind: type: string const: provider expiresAt: type: string minLength: 1 headers: type: object propertyNames: type: string minLength: 1 additionalProperties: type: string minLength: 1 required: - kind - expiresAt - headers additionalProperties: false required: - status - apiBaseUrl - mcpUrl - credentials additionalProperties: false - type: object properties: status: type: string enum: - starting - dead apiBaseUrl: type: 'null' mcpUrl: type: 'null' credentials: type: 'null' required: - status - apiBaseUrl - mcpUrl - credentials additionalProperties: false expiresAt: type: string minLength: 1 certificationWarnings: type: array items: type: object properties: environmentId: type: string minLength: 1 maxLength: 80 code: type: string const: ENVIRONMENT_CERTIFICATION_DEGRADED message: type: string minLength: 1 certification: type: object properties: status: type: string enum: - healthy - degraded - quarantined - unknown admission: type: string enum: - allow - warn - deny checkedAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' evidenceSha256: anyOf: - type: string pattern: ^[a-f0-9]{64}$ - type: 'null' required: - status - admission - checkedAt - evidenceSha256 additionalProperties: false required: - environmentId - code - message - certification additionalProperties: false lease: type: object properties: expiresAt: type: string minLength: 1 idleExpiresAt: anyOf: - type: string minLength: 1 - type: 'null' hardExpiresAt: type: string minLength: 1 renewable: type: boolean required: - expiresAt - idleExpiresAt - hardExpiresAt - renewable additionalProperties: false workspace: type: object properties: id: type: string minLength: 1 name: type: string minLength: 1 required: - id additionalProperties: false required: - sessionId - status - environmentIds - environments - expiresAt additionalProperties: false '400': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true '401': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true '402': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true '403': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true '404': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true '409': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true '413': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true '429': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true '500': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true '502': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true '503': description: The request was rejected headers: X-Request-Id: description: Request correlation identifier schema: type: string Retry-After: description: Seconds to wait before retrying when present schema: type: integer minimum: 0 content: application/json: schema: type: object properties: ok: type: boolean error: type: string code: type: string message: type: string requestId: type: string issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: true additionalProperties: true security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Archal workspace API key description: Used by lifecycle, catalog, and state endpoints ````