Skip to main content
The Agent API lets you send tasks to Jarvis agents, poll for results, and review past activity. Jarvis supports two agents: Paperclip and Hermes. All requests require an Authorization header. See the API overview for authentication details.

​
POST /agents/invoke

Send a task to an agent. Jarvis queues the task and returns a task ID you can use to check its status.

​
Request

​
agent
string
required
The agent to invoke. Accepted values: paperclip, hermes.
​
task
string
required
A natural-language description of the task you want the agent to perform.
​
context
object
Optional key-value pairs passed to the agent as additional context (e.g., file paths, prior conversation, environment variables).
​
priority
string
Task priority. Accepted values: low, normal, high. Defaults to normal.

​
Response

​
task_id
string
A unique identifier for the queued task. Use this with GET /agents/status/{id}.
​
agent
string
The agent that will handle the task.
​
status
string
Initial task status. Always queued on a successful invoke.
​
created_at
string
ISO 8601 timestamp for when the task was created.

​
Example

curl
curl -X POST https://your-jarvis-host/agents/invoke \
  -H "Authorization: Bearer jrv_yourkey123" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "paperclip",
    "task": "Review open GitHub issues and draft a prioritized triage summary.",
    "priority": "normal"
  }'
Response
{
  "task_id": "tsk_01j8z4kx9m3rq7v",
  "agent": "paperclip",
  "status": "queued",
  "created_at": "2026-04-04T10:22:01Z"
}

​
GET /agents/status/

Check the current status of a task.

​
Path parameter

​
id
string
required
The task ID returned by POST /agents/invoke.

​
Response

​
task_id
string
The task identifier.
​
agent
string
The agent assigned to the task.
​
status
string
Current task status. One of: queued, running, completed, failed.
​
result
string
The agent’s output. Present only when status is completed.
​
error
string
Error message. Present only when status is failed.
​
started_at
string
ISO 8601 timestamp for when the agent started working on the task.
​
completed_at
string
ISO 8601 timestamp for when the task finished. Present only when status is completed or failed.

​
Example

curl
curl https://your-jarvis-host/agents/status/tsk_01j8z4kx9m3rq7v \
  -H "Authorization: Bearer jrv_yourkey123"
Response
{
  "task_id": "tsk_01j8z4kx9m3rq7v",
  "agent": "paperclip",
  "status": "completed",
  "result": "Here is a prioritized triage summary of the 12 open issues...",
  "started_at": "2026-04-04T10:22:04Z",
  "completed_at": "2026-04-04T10:22:41Z"
}

​
GET /agents/history

List recent agent tasks across all agents, ordered by most recent first.

​
Query parameters

​
agent
string
Filter results to a specific agent. Accepted values: paperclip, hermes.
​
status
string
Filter by task status. Accepted values: queued, running, completed, failed.
​
limit
integer
Maximum number of tasks to return. Defaults to 20. Maximum is 100.
​
offset
integer
Number of tasks to skip for pagination. Defaults to 0.

​
Response

​
tasks
array
An array of task summary objects.
​
total
integer
Total number of tasks matching the query (before pagination).

​
Example

curl
curl "https://your-jarvis-host/agents/history?agent=hermes&limit=5" \
  -H "Authorization: Bearer jrv_yourkey123"
Response
{
  "tasks": [
    {
      "task_id": "tsk_01j8z9wx2n4sp1k",
      "agent": "hermes",
      "task": "Deploy updated Docker image to staging.",
      "status": "completed",
      "created_at": "2026-04-04T09:55:12Z"
    }
  ],
  "total": 1
}
Use GET /agents/history combined with your n8n workflows to build automated reporting on agent activity.