Skip to main content
POST
Requires version 2.0.1 or later of the Archetype platform.

Overview

This endpoint opens a session on a deployment. The deployment must be ready, and the session runs the deployment’s package. A session on a batch deployment is one run over its own input files, given in connectors. The platform submits one job for it, and the session moves from pending to running, then ends as completed, failed, or cancelled. Poll Get Session to follow it, then read what it produced with Get Session Results. A session on a serving deployment sends its inputs to the deployed agent with Query Session, so it takes no connectors. It can run with values of its own. It runs until you cancel it, its deployment ends, or it ends on its own, for example after its idle timeout; its error says why. Opening a serving session can take up to 60 seconds, so do not retry before the call returns. The session is in its deployment’s project, and opening it requires being able to modify that project. A batch session’s job runs as the project’s creator, so its source files must be files the project’s creator can read. The endpoint returns 202 Accepted with the session in its initial status, which may be pending or already running. Query a serving session once it is running.

Request

string
required
The dpl_ id of the deployment to open the session on. It must be ready.
object
The session’s input files and optional output file. Required for a batch session, which reads its input from them, so source must list at least one file ref. A serving session must omit connectors.
array
One or more input refs. Each entry is a data ref.
object
Optional output ref; omit it or send null for the default. It must not name a file that already exists.
object
Values a serving session runs with, by name, over its deployment’s. Each must be one the blueprint declares, and reach only a node’s session fields. Omitted, null and {} mean none. A batch session refuses non-empty values with 422. v2.0.1+

Data ref

string
required
Storage kind, for example file.
string
required
Identifier within that storage kind, for example file_abc123.
string
Optional format hint, for example csv.

Response

Returns 202 Accepted with the created session.
string
required
The session’s ses_ id.
string
required
The deployment the session runs in.
string
required
The deployment’s package.
string
required
Owning organization.
string
required
The project the session is in: its deployment’s.
string
required
Who opened the session: a user’s usr_ id, or the key_ id of the service-account API key it was opened with.
string
required
How the session runs: always its deployment’s kind, batch or serving.
string
required
Where the session is in its lifecycle: pending, running, completed, failed, or cancelled. The last three are terminal.
object
A batch session’s input files and optional output file; null for a serving session.
string
The job running a batch session, once it has been dispatched; null before that and for a serving session.
string
Why the session failed, or why the platform cancelled it; null otherwise.
string
required
When the session was created (date-time).
string
When it started running; null until then.
string
When it reached a terminal status; null until then.
object
The session’s own values; null when it has none. v2.0.1+

Important Notes

  • A 400 means the body does not parse (invalid_request_body), a batch session has no connectors, no file among its sources, or a source file that does not exist or the project’s creator cannot read, or a serving session gives connectors.
  • A 403 means you can see the deployment’s project but cannot modify it. In a free trial, a 403 with the code capability_locked means the package’s blueprint is not available in the free trial.
  • A 404 means the deployment does not exist, belongs to another organization, or is in a project you cannot see.
  • A 409 means the deployment is not ready (for example, it was stopped) or its agent has stopped, with the reason in the message, or the sink names a file that already exists.
  • A 409 with the code deployment_sessions_unsupported means values were given and the deployment runs without sessions. Deploy the package again.
  • A 422 with the code values_not_supported means values were given for a batch session; invalid_session_values means the values cannot be applied, named in the message; session_channel_collision means the blueprint’s WebSocket channel is not keyed per session.
  • A 429 with the code session_limit_reached means the deployment holds its max sessions. Cancel one, or wait for one to end.
  • A 500 with the code internal_error means the deployment cannot build a session. Retrying will not help.
  • A 502 with the code worker_unavailable means the session could not be opened and nothing was created. Retry.
  • A 503 with the code unavailable means the deployment cannot be reached just now. Retry.
  • A session that is pending or running can be cancelled with Cancel Session.