> ## 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.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 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: - annotations - deleteOnLastSessionExit - 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 required: - extendedEndReport title: SessionRuntimeSettings 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 - type: object description: A remote agent provided by a specific server properties: type: type: string enum: - remote title: String server: $ref: '#/components/schemas/GraphAgentServer' description: The server that is providing this remote agent runtime: $ref: '#/components/schemas/RuntimeId' description: >- The runtime to be used on the remote server. Likely Docker or Phala wallet: type: string description: >- The wallet address of the server that is providing this remote agent title: String maxCost: anyOf: - type: object properties: type: type: string enum: - coral title: String amount: type: number format: double title: Double required: - amount - type title: coral - type: object properties: type: type: string enum: - micro_coral title: String amount: type: integer format: int64 title: Long required: - amount - type title: micro_coral - type: object properties: type: type: string enum: - usd title: String amount: type: number format: double title: Double required: - amount - type title: usd description: The max cost of this agent discriminator: propertyName: type title: AgentClaimAmount paymentSessionId: type: string description: >- The payment session ID for this remote agent. This will be shared with all other remote agents in the graph title: String required: - maxCost - paymentSessionId - runtime - server - type - wallet title: remote - type: object description: >- A request for a remote agent and a list of places to try and source a server from properties: type: type: string enum: - remote_request title: String runtime: $ref: '#/components/schemas/RuntimeId' description: >- The runtime that should be used for this remote agent. Servers can export only specific runtimes so the runtime choice may narrow servers that can adequately provide the agent maxCost: anyOf: - type: object properties: type: type: string enum: - coral title: String amount: type: number format: double title: Double required: - amount - type title: coral - type: object properties: type: type: string enum: - micro_coral title: String amount: type: integer format: int64 title: Long required: - amount - type title: micro_coral - type: object properties: type: type: string enum: - usd title: String amount: type: number format: double title: Double required: - amount - type title: usd description: >- The maximum we are willing to pay for this remote agent, note that if this is not high enough there may be no remotes willing to provide the agent discriminator: propertyName: type title: AgentClaimAmount serverSource: anyOf: - type: object properties: type: type: string enum: - >- org.coralprotocol.coralserver.agent.graph.server.GraphAgentServerSource.Indexer title: String indexer: type: string title: String required: - indexer - type title: Indexer - type: object properties: type: type: string enum: - servers title: String servers: type: array items: $ref: '#/components/schemas/GraphAgentServer' title: ArrayList required: - servers - type title: servers description: >- A description of which servers should be queried for this remote agent request discriminator: propertyName: type title: GraphAgentServerSource serverScoring: anyOf: - type: object description: >- Custom server scoring. Weights can be added on a flat or multiplier basis per attribute properties: type: type: string enum: - custom title: String scorers: type: array items: anyOf: - type: object description: >- The effect will be applied for every attribute of the specified type with a boolean false value properties: op: type: string enum: - is_false title: String type: $ref: >- #/components/schemas/GraphAgentServerAttributeType effect: $ref: '#/components/schemas/flat' description: A flat negative or positive weight required: - effect - op - type title: is_false - type: object description: >- The effect will be applied if the no attribute of the specified type is present properties: op: type: string enum: - is_not_present title: String type: $ref: >- #/components/schemas/GraphAgentServerAttributeType effect: $ref: '#/components/schemas/flat' description: A flat negative or positive weight required: - effect - op - type title: is_not_present - type: object description: >- The effect will be applied for every attribute of the specified type properties: op: type: string enum: - is_present title: String type: $ref: >- #/components/schemas/GraphAgentServerAttributeType effect: $ref: >- #/components/schemas/GraphAgentServerScorerEffect required: - effect - op - type title: is_present - type: object description: >- The effect will be applied for every attribute of the specified type with a boolean true value properties: op: type: string enum: - is_true title: String type: $ref: >- #/components/schemas/GraphAgentServerAttributeType effect: $ref: '#/components/schemas/flat' description: A flat negative or positive weight required: - effect - op - type title: is_true - type: object description: >- The effect will be applied for every attribute of the specified type with a matching string value properties: op: type: string enum: - string_equal title: String type: $ref: >- #/components/schemas/GraphAgentServerAttributeType string: type: string title: String effect: $ref: '#/components/schemas/flat' description: A flat negative or positive weight required: - effect - op - string - type title: string_equal - type: object description: >- The effect will be applied for every attribute of the specified type with a non-matching string value properties: op: type: string enum: - string_not_equal title: String type: $ref: >- #/components/schemas/GraphAgentServerAttributeType string: type: string title: String effect: $ref: '#/components/schemas/flat' description: A flat negative or positive weight required: - effect - op - string - type title: string_not_equal discriminator: propertyName: op title: GraphAgentServerCustomScorer title: ArrayList required: - scorers - type title: custom - type: object description: >- Default server scoring. No weights assigned to any server attribute properties: type: type: string enum: - default title: String required: - type title: default description: Customisation for the scoring of servers discriminator: propertyName: type title: GraphAgentServerScoring required: - maxCost - runtime - serverSource - type title: remote_request 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 annotations: type: object additionalProperties: type: string title: String title: LinkedHashMap required: - id - name - provider - proxies 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: - inputSchema - outputSchema - 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 GraphAgentServer: type: object properties: address: type: string title: String port: type: integer maximum: 65535 minimum: 0 title: UShort secure: type: boolean title: Boolean attributes: type: array items: anyOf: - type: object properties: format: type: string enum: - boolean title: String type: $ref: '#/components/schemas/GraphAgentServerAttributeType' value: type: boolean title: Boolean required: - format - type - value title: boolean - type: object properties: format: type: string enum: - number title: String type: $ref: '#/components/schemas/GraphAgentServerAttributeType' value: type: number format: double title: Double required: - format - type - value title: number - type: object properties: format: type: string enum: - string title: String type: $ref: '#/components/schemas/GraphAgentServerAttributeType' value: type: string title: String required: - format - type - value title: string discriminator: propertyName: format title: GraphAgentServerAttribute title: ArrayList required: - address - attributes - port - secure title: GraphAgentServer GraphAgentServerAttributeType: type: string enum: - geographic_location - attested_by title: GraphAgentServerAttributeType flat: type: object description: A flat negative or positive weight properties: weight: type: number format: double title: Double required: - weight title: flat GraphAgentServerScorerEffect: anyOf: - type: object description: A flat negative or positive weight properties: weight: type: number format: double title: Double required: - weight title: flat - type: object description: >- A multiplier weight, this effect will only multiply against attributes with a number type properties: weight: type: number format: double title: Double required: - weight title: multiplier title: GraphAgentServerScorerEffect 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 ToolSchema: type: object properties: 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 ````