Skip to main content
POST /v1/deployments/:deployment_id/messages
Sends a message to the agent and starts a run. Responses stream over the deployment’s SSE events endpoint — this endpoint returns immediately with the run ID. Every deployment is created with a default thread (thread_id in the Create Deployment response). Omit thread_id to use it, or pass "thread_id": "new" to start a fresh conversation with the same agent — memory and the filesystem carry over, the conversation history does not.

​
Request

curl "https://api.prismagents.com/v1/deployments/dep_7xK9s2/messages" \
  -X POST \
  -H "Authorization: Bearer $PRISM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Make five variations of last week'\''s top-performing video.",
    "attachments": [
      {
        "type": "video",
        "url": "https://cdn.example.com/top-video.mp4"
      }
    ]
  }'

​
Path parameters

ParameterTypeRequiredDescription
deployment_idstringYesDeployment ID

​
Body parameters

ParameterTypeRequiredDescription
contentstringYesThe message text
thread_idstringNoThread to post to. Omit for the default thread, or "new" for a fresh thread
attachmentsarrayNoImage, video, or audio inputs — see Attachments

​
Attachments

Agents accept image and video inputs natively.
FieldTypeRequiredDescription
typestringYesOne of image, video, or audio
urlstringYesPublicly fetchable URL of the file

​
Response

{
  "run_id": "run_4mPx81",
  "deployment_id": "dep_7xK9s2",
  "thread_id": "thr_default_8a1",
  "status": "running"
}

​
Response fields

FieldTypeDescription
run_idstringRun identifier — events for this run carry it
thread_idstringThread the message was posted to
statusstringOne of running, waiting_on_human, completed, error

​
Mid-run messages

Sending a new message while a run is in progress does not corrupt state: the agent treats it as steering input and folds it into the run in flight.

​
Errors

StatusErrorWhen
400validation_errorInvalid JSON request body
401unauthorizedMissing or invalid API key
402insufficient_creditsThe account does not have enough credits
403forbiddenAPI key lacks deployments:write scope
404not_foundDeployment or thread does not exist
409deployment_not_readyThe deployment is still provisioning
See Errors for the full error reference.