> ## Documentation Index > Fetch the complete documentation index at: https://docs.coralos.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create session > Creates a new session in a given namespace ## OpenAPI ````yaml /api_v1.json post /api/v1/local/session openapi: 3.1.0 info: title: Coral Server API version: 1.5.0 servers: [] security: [] tags: [] externalDocs: url: / paths: /api/v1/local/session: post: tags: - local summary: Create session description: Creates a new session in a given namespace operationId: createSession parameters: [] requestBody: description: >- The session request body, containing the agents to use in the session and other settings content: application/json: schema: $ref: '#/components/schemas/SessionRequest' required: false responses: '200': description: Success headers: {} content: application/json: schema: $ref: '#/components/schemas/SessionIdentifier' '400': description: The agent graph is invalid and could not be processed headers: {} content: application/json: schema: $ref: '#/components/schemas/RouteException' '403': description: Invalid application ID or privacy key headers: {} content: application/json: schema: $ref: '#/components/schemas/RouteException' deprecated: false security: - token: [] components: schemas: SessionRequest: type: object properties: agentGraphRequest: $ref: '#/components/schemas/AgentGraphRequest' description: A request for the agents in this session namespaceProvider: anyOf: - type: object description: |2- Provides a full namespace request to create an ad hoc namespace if the namespace doesn't already exist. Note that this will not update an existing namespace, so for example, there is no guarantee that annotations specified on this request end up on the namespace that this session belongs in. properties: type: type: string enum: - create_if_not_exists title: String namespaceRequest: $ref: '#/components/schemas/SessionNamespaceRequest' required: - namespaceRequest - type title: create_if_not_exists - type: object description: >- Indicates that the session request should use an existing namespace properties: type: type: string enum: - use_existing title: String name: type: string title: String required: - name - type title: use_existing description: A description of what namespace this session should run in discriminator: propertyName: type title: SessionNamespaceProvider execution: anyOf: - type: object description: >- The session's execution is deferred. A deferred execution must be executed manually later properties: mode: type: string enum: - defer title: String required: - mode title: defer - type: object description: >- The session should be executed immediately with the specified runtime settings properties: mode: type: string enum: - immediate title: String runtimeSettings: $ref: '#/components/schemas/SessionRuntimeSettings' required: - mode title: immediate discriminator: propertyName: mode title: SessionRequestExecution budgetSettings: $ref: '#/components/schemas/SessionBudgetSettings' description: >- Budget settings for this session. See SessionBudgetSettings for more information annotations: type: object additionalProperties: type: string title: String title: LinkedHashMap required: - agentGraphRequest - namespaceProvider title: SessionRequest SessionIdentifier: type: object properties: namespace: type: string description: The namespace that this session belongs in title: String sessionId: type: string description: The unique identifier for the session title: String required: - namespace - sessionId title: SessionIdentifier RouteException: type: object properties: message: type: string title: String required: - message title: RouteException AgentGraphRequest: type: object properties: agents: type: array description: Every agent required for this agent graph items: $ref: '#/components/schemas/GraphAgentRequest' title: ArrayList groups: type: array description: A set, containing sets that define the agent groups by name items: type: array items: type: string title: String title: LinkedHashSet uniqueItems: true title: LinkedHashSet> uniqueItems: true customTools: type: object additionalProperties: $ref: '#/components/schemas/GraphAgentTool' description: A map of custom tools to provide to the agents in this graph title: LinkedHashMap required: - agents title: AgentGraphRequest SessionNamespaceRequest: type: object properties: name: type: string description: The name of this namespace title: String deleteOnLastSessionExit: type: boolean description: |2- If this is true the namespace will be deleted when the last session in this namespace closes. Note that this does not guarantee that the namespace will never be empty, because namespaces can be created without sessions title: Boolean annotations: type: object additionalProperties: type: string title: String title: LinkedHashMap required: - name title: SessionNamespaceRequest SessionRuntimeSettings: type: object properties: ttl: type: integer format: int64 description: >- If specified, the session will never live longer than this many milliseconds. title: Long extendedEndReport: type: boolean description: >- If specified, the end report generated for this session will be extended, including threads and messages title: Boolean persistenceMode: anyOf: - type: object description: >- Session will exist for at least the specified time (in milliseconds) after the session exits. This time does not include the run time of the session. properties: mode: type: string enum: - hold_after_exit title: String duration: type: integer format: int64 title: Long required: - duration - mode title: hold_after_exit - type: object description: >- Session will exist for at least the specified time (in milliseconds). This time includes the run time of the session. properties: mode: type: string enum: - minimum_time title: String time: type: integer format: int64 title: Long required: - mode - time title: minimum_time - type: object description: No persistence properties: mode: type: string enum: - none title: String required: - mode title: none description: >- Persistence mode for the session. Default is "none" meaning the session will be deleted as soon as it exits discriminator: propertyName: mode title: SessionPersistenceMode webhooks: $ref: '#/components/schemas/SessionWebhooks' description: Webhooks executed for this session title: SessionRuntimeSettings SessionBudgetSettings: type: object description: >- Budgets settings for this session. Budgets are consumed by agents in the session. properties: budget: type: integer description: |2- This budget is shared across all agents in the session and can be used by any agent configured to consume the shared budget. The value is specified in micro cents. $1.00 is 100000000 and $0.01 is 1000000.") title: AgentBudgetUnit exhaustionBehavior: anyOf: - type: object description: >- The exhaustion of the session's budget will be ignored. This has a high chance of overclaiming. properties: type: type: string enum: - ignore title: String required: - type title: ignore - type: object description: >- Once the session budget drops below the specified minimum, agents that claim for it will be killed. The higher the minimum is the lower the chance of overclaiming. properties: type: type: string enum: - kill_agent title: String minimum: type: integer description: >- The minimum value, specified in micro cents. $1.00 is 100000000 and $0.01 is 1000000. title: AgentBudgetUnit force: type: boolean description: >- If this is true, when an agent claims from the session budget that is below the minimum, the agent will be killed immediately. If this is false, the agent will only be killed if the agent requests for automatic closing. title: Boolean forceDelay: type: string description: >- If force killing is enabled, it will be delayed by this amount before the agent is killed. If this delay is too low the agent may be killed before it handles to response to a claim title: Duration required: - force - minimum - type title: kill_agent - type: object description: >- Once the session budget drops below the specified minimum, agents that claim for it will trigger the session to be killed. The higher the minimum is the lower the chance of overclaiming. properties: type: type: string enum: - kill_session title: String minimum: type: integer description: >- The minimum value, specified in micro cents. $1.00 is 100000000 and $0.01 is 1000000. title: AgentBudgetUnit delay: type: string description: >- The delay before the session is killed. If this delay is too low, the agent whose claim triggered this may be killed before it receives the response to that claim title: Duration required: - minimum - type title: kill_session description: |2- The behavior for agents consuming from this budget after it has been exhausted. Note that this behavior only applies to agents that consume from the session budgets. Agents that have their own budget will first perform behaviors described by the agent's own budget settings. discriminator: propertyName: type title: SessionBudgetExhaustionBehavior title: SessionBudgetSettings GraphAgentRequest: type: object description: A request for an agent. GraphAgentRequest -> GraphAgent properties: id: $ref: '#/components/schemas/RegistryAgentIdentifier' description: The ID of this agent in the registry name: type: string description: A given name for this agent in the session/group title: String description: type: string description: An optional override for the description of this agent title: String options: type: object additionalProperties: anyOf: - type: object properties: type: type: string enum: - blob title: String value: type: string title: String required: - type - value title: blob - type: object properties: type: type: string enum: - list[blob] title: String value: type: array items: type: string title: String title: ArrayList required: - type - value title: list[blob] - type: object properties: type: type: string enum: - bool title: String value: type: boolean title: Boolean required: - type - value title: bool - type: object properties: type: type: string enum: - i8 title: String value: type: integer maximum: 127 minimum: -128 title: Byte required: - type - value title: i8 - type: object properties: type: type: string enum: - list[i8] title: String value: type: array items: type: integer maximum: 127 minimum: -128 title: Byte title: ArrayList required: - type - value title: list[i8] - type: object properties: type: type: string enum: - f64 title: String value: type: number format: double title: Double required: - type - value title: f64 - type: object properties: type: type: string enum: - list[f64] title: String value: type: array items: type: number format: double title: Double title: ArrayList required: - type - value title: list[f64] - type: object properties: type: type: string enum: - f32 title: String value: type: number format: float title: Float required: - type - value title: f32 - type: object properties: type: type: string enum: - list[f32] title: String value: type: array items: type: number format: float title: Float title: ArrayList required: - type - value title: list[f32] - type: object properties: type: type: string enum: - i32 title: String value: type: integer format: int32 title: Int required: - type - value title: i32 - type: object properties: type: type: string enum: - list[i32] title: String value: type: array items: type: integer format: int32 title: Int title: ArrayList required: - type - value title: list[i32] - type: object properties: type: type: string enum: - i64 title: String value: type: integer format: int64 title: Long required: - type - value title: i64 - type: object properties: type: type: string enum: - list[i64] title: String value: type: array items: type: integer format: int64 title: Long title: ArrayList required: - type - value title: list[i64] - type: object properties: type: type: string enum: - i16 title: String value: type: integer maximum: 32767 minimum: -32768 title: Short required: - type - value title: i16 - type: object properties: type: type: string enum: - list[i16] title: String value: type: array items: type: integer maximum: 32767 minimum: -32768 title: Short title: ArrayList required: - type - value title: list[i16] - type: object properties: type: type: string enum: - string title: String value: type: string title: String required: - type - value title: string - type: object properties: type: type: string enum: - list[string] title: String value: type: array items: type: string title: String title: ArrayList required: - type - value title: list[string] - type: object properties: type: type: string enum: - u8 title: String value: type: integer maximum: 255 minimum: 0 title: UByte required: - type - value title: u8 - type: object properties: type: type: string enum: - list[u8] title: String value: type: array items: type: integer maximum: 255 minimum: 0 title: UByte title: ArrayList required: - type - value title: list[u8] - type: object properties: type: type: string enum: - u32 title: String value: type: integer maximum: 4294967295 minimum: 0 title: UInt required: - type - value title: u32 - type: object properties: type: type: string enum: - list[u32] title: String value: type: array items: type: integer maximum: 4294967295 minimum: 0 title: UInt title: ArrayList required: - type - value title: list[u32] - type: object properties: type: type: string enum: - u64 title: String value: type: string title: String required: - type - value title: u64 - type: object properties: type: type: string enum: - list[u64] title: String value: type: array items: type: string title: String title: ArrayList required: - type - value title: list[u64] - type: object properties: type: type: string enum: - u16 title: String value: type: integer maximum: 65535 minimum: 0 title: UShort required: - type - value title: u16 - type: object properties: type: type: string enum: - list[u16] title: String value: type: array items: type: integer maximum: 65535 minimum: 0 title: UShort title: ArrayList required: - type - value title: list[u16] discriminator: propertyName: type title: AgentOptionValue description: The arguments to pass to the agent title: LinkedHashMap systemPrompt: type: string description: The system prompt/developer text/preamble passed to the agent title: String blocking: type: boolean description: >- All blocking agents in a group must be instantiated before the group can communicate. Non-blocking agents' contributions to groups are optional title: Boolean customToolAccess: type: array description: >- A list of custom tools that this agent can access. The custom tools must be defined in the parent AgentGraphRequest object items: type: string title: String title: LinkedHashSet uniqueItems: true plugins: type: array description: >- Plugins that should be installed on this agent. See GraphAgentPlugin for more information items: anyOf: - type: object properties: type: type: string enum: - close_session_tool title: String required: - type title: close_session_tool discriminator: propertyName: type title: GraphAgentPlugin title: LinkedHashSet uniqueItems: true provider: anyOf: - type: object description: The agent will be provided by a linked server properties: type: type: string enum: - linked title: String linkedServerName: type: string title: String runtime: $ref: '#/components/schemas/RuntimeId' required: - linkedServerName - runtime - type title: linked - type: object description: The agent will be provided by this server properties: type: type: string enum: - local title: String runtime: $ref: '#/components/schemas/RuntimeId' required: - runtime - type title: local description: The server that should provide this agent and the runtime to use discriminator: propertyName: type title: GraphAgentProvider x402Budgets: type: array description: >- An optional list of resources and an accompanied budget that this agent may spend on services that accept x402 payments items: $ref: '#/components/schemas/X402BudgetedResource' title: ArrayList proxies: type: object additionalProperties: $ref: '#/components/schemas/GraphAgentProxyRequest' description: >- A map where the key is the name of the proxy request and the value is the configuration and model that should be selected. title: LinkedHashMap budgetSettings: $ref: '#/components/schemas/GraphAgentBudgetSettings' description: >- Budget settings for this agent. By default the agent has no budget of its own, and can only claim from the sessions budget. annotations: type: object additionalProperties: type: string title: String title: LinkedHashMap required: - id - name - provider title: GraphAgentRequest GraphAgentTool: type: object properties: transport: anyOf: - type: object properties: type: type: string enum: - http title: String url: type: string title: String signatureHeader: type: string title: String required: - type - url title: http discriminator: propertyName: type title: GraphAgentToolTransport inputSchema: $ref: '#/components/schemas/ToolSchema' outputSchema: $ref: '#/components/schemas/ToolSchema' description: type: string title: String title: type: string title: String annotations: $ref: '#/components/schemas/ToolAnnotations' required: - transport title: GraphAgentTool SessionWebhooks: type: object properties: sessionEnd: $ref: '#/components/schemas/SessionEndWebhook' description: >- The webhook that is called when this session ends. The model sent is a SessionEndState title: SessionWebhooks RegistryAgentIdentifier: type: object properties: name: type: string description: The exact name of the agent in the registry title: String version: type: string description: The exact version of the agent in the registry title: String registrySourceId: anyOf: - type: object properties: type: type: string enum: - linked title: String linkedServerId: type: string title: String required: - linkedServerId - type title: linked - type: object properties: type: type: string enum: - local title: String required: - type title: local - type: object properties: type: type: string enum: - marketplace title: String required: - type title: marketplace description: The identifier for the registry source that contains this agent discriminator: propertyName: type title: AgentRegistrySourceIdentifier required: - name - registrySourceId - version title: RegistryAgentIdentifier RuntimeId: type: string enum: - executable - docker - function - prototype title: RuntimeId X402BudgetedResource: type: object description: A budget given to an agent for a specific resource properties: priority: type: integer format: int32 description: >- The priority of this budget. If a x402 service accepts multiple resources and an agent was given a budget for multiple resources, the resource with the highest priority will be used until it is consumed title: Int resource: type: string description: The this budget is for title: String remainingBudget: type: integer description: The remaining budget for this resource in atomic units title: ULong required: - priority - remainingBudget - resource title: X402BudgetedResource GraphAgentProxyRequest: type: object properties: configurationName: type: string description: The name of the LLM proxy configuration title: String modelName: type: string description: The name of the model title: String required: - configurationName - modelName title: GraphAgentProxyRequest GraphAgentBudgetSettings: type: object properties: budget: type: integer description: >- The budget for this specific agent. The value is specified in micro cents. $1.00 is 100000000 and $0.01 is 1000000. title: AgentBudgetUnit claimTypeCosts: type: object additionalProperties: type: integer title: AgentBudgetUnit description: >- A map where each key is a claim type name and the value the cost for that claim. Claims that do not have default values set must have their values set in this map or else they will not contribute to the budget. title: LinkedHashMap exhaustionBehavior: anyOf: - type: object description: >- Once's the agent's budget is exhausted, it will consume the session's budget. If the session's budget is also exhausted, the session's exhaustion behavior will be applied. If a claim is made that cannot be fully fulfilled by the agent's budget, the remainder will be taken from the session's budget. properties: type: type: string enum: - consume_session title: String required: - type title: consume_session - type: object description: >- Once the agent's budget is less than the specified minimum amount, the agent will be killed. The higher the minimum is the lower the chance of overclaiming. This behavior will stop the agent claiming from the session's budget properties: type: type: string enum: - kill title: String minimum: type: integer description: >- The minimum value, specified in micro cents. $1.00 is 100000000 and $0.01 is 1000000. title: AgentBudgetUnit force: type: boolean description: >- If this is true, the agent will be killed immediately. If this is false, the agent will only be killed if the claim requests for automatic closing. title: Boolean forceDelay: type: string description: >- If force killing is enabled, it will be delayed by this amount before the agent is killed. If this delay is too low the agent may be killed before it handles to response to a claim title: Duration required: - force - minimum - type title: kill description: >- The behavior of agent budget exhaustion, defaults to consuming session budget. discriminator: propertyName: type title: AgentBudgetExhaustionBehavior title: GraphAgentBudgetSettings ToolSchema: type: object properties: $schema: type: string title: String properties: type: object additionalProperties: $ref: '#/components/schemas/JsonElement' title: JsonObject required: type: array items: type: string title: String title: ArrayList $defs: type: object additionalProperties: $ref: '#/components/schemas/JsonElement' title: JsonObject type: type: string title: String required: - type title: ToolSchema ToolAnnotations: type: object properties: title: type: string title: String readOnlyHint: type: boolean title: Boolean destructiveHint: type: boolean title: Boolean idempotentHint: type: boolean title: Boolean openWorldHint: type: boolean title: Boolean title: ToolAnnotations SessionEndWebhook: type: object description: >- The webhook that is called when this session ends. The model sent is a SessionEndState properties: url: type: string title: String required: - url title: SessionEndWebhook JsonElement: type: object properties: {} title: JsonElement securitySchemes: token: type: http scheme: bearer bearerFormat: Configured token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.