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

Overview

This endpoint deploys a package. A deployment is a package placed on a runtime. Once the deployment is ready, you open sessions on it with Create Session. On a batch deployment, each session is one run over its own input files. On a serving deployment, each session sends its inputs to the deployed agent with Query Session. The package must be ready, built for the platform target, hold exactly one blueprint, and be in a project. The deployment is in its package’s project, and creating it requires being able to modify that project. The endpoint returns 202 Accepted with the deployment in its initial status, which may be deploying or already ready. Poll Get Deployment until it is ready before you open a session. A deployment that cannot be started, is not ready within the platform’s start deadline, or stops working later becomes failed, with the reason in error, and its sessions fail with it. Where the platform stops idle deployments, a ready serving deployment that no session has queried for that long becomes stopped and its sessions cancelled, each with an event giving the reason. Either end is final: to run the package again, deploy it again.

Request

string
required
The pkg_ id of the package to deploy. It must be ready, built for the platform target, hold exactly one blueprint, and be in a project.
string
required
What to deploy the package as. batch: each session opened on the deployment is one run over its own input files. serving: the deployed agent answers queries from every session opened on it.
object
Limits for a serving deployment’s sessions. A batch deployment refuses it with 400. Leave it out, send null, or leave out any field for the defaults. Change them later with Update Deployment.
integer
default:"16"
The most sessions the deployment holds open at once, per running copy of the deployment. Minimum 1, maximum 1000.
integer
default:"1800"
Seconds a session can sit unused, counted from its last use, before the deployment closes it. Maximum 86400. 0 means never, which is refused with 400 where the platform stops idle deployments.

Response

Returns 202 Accepted with the created deployment.
string
required
The deployment’s dpl_ id.
string
required
Owning organization.
string
required
The project the deployment is in: its package’s.
string
required
Who created the deployment: a user’s usr_ id, or the key_ id of the service-account API key it was created with.
string
required
The package deployed.
string
required
What the package is deployed as: batch or serving.
string
required
Where the deployment is in its lifecycle: deploying, ready, stopped, or failed. Sessions can be opened only on a ready deployment.
string
Why the deployment failed; null otherwise.
string
required
When the deployment was created (date-time).
string
When sessions could first be opened on it; null until it is ready.
string
When it stopped; null until it is stopped or failed.
object
The session settings stored for a serving deployment: max and idle_timeout_secs. null for a batch deployment.

Important Notes

  • A 400 means the body does not parse (invalid_request_body), a sessions value is outside its limits (out_of_range), sessions is given for a batch deployment or idle_timeout_secs is 0 where idle deployments are stopped (bad_request), or the package was built for a target other than platform or holds more than one blueprint.
  • A 400 with the code project_required means the package is not in a project. Move it into a project, or build one there.
  • For a serving deployment, a 400 also means the package’s blueprint cannot be served, needs hardware or a capability the platform does not provide, or sets a setting the platform owns.
  • A 429 with the code serving_limit_reached means your organization already has as many serving deployments as it may. Stop one before you deploy another.
  • A 403 means you can see the package’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 package does not exist, belongs to another organization, or is in a project you cannot see.
  • A 409 means the package is not ready. If it is still building, poll Get Package until it is ready.
  • A deployed package, and its project, cannot be deleted. Stop and delete the deployment first.