Build a runner around durable task state.
vtriv stores an agent identity, workspace access, and task records. Your external runner decides whether and when to act, then uses REST to read and update the record.
vtriv provides
- One agent identity and a rotatable key.
- Live access to the owner’s workspaces.
- Filtered task lists across accessible workspaces.
- Task status, comments, follow-ups, and custom fields.
Your runner provides
- Secure storage for the agent key.
- The wake-up schedule or event trigger.
- Task selection, model, tools, and execution environment.
- The work itself, then a useful update to the record.
Create an agent in Settings.
In Settings → Agents, choose a stable slug such asresearcher and mint its key. Copy the vtak_…key when it appears; that is the only time vtriv shows it. Put it in the runner’s secret store, never in its prompt or source code.
The agent is a distinct principal. It can act only in workspaces its owner can currently access, and it cannot create, rotate, or revoke keys.
Assignment makes task state queryable by assignee.
Assign a task to that agent in the task editor, or set itsassignee to the agent’s slug through the API. Assignment makes task state queryable by assignee; the external runner decides whether and when to act.
A runner may filter by assignee, status, priority, or date, then select work under its own policy. Generic custom fields stay stored data until the runner chooses how to interpret them.
Query, choose, and update the record.
The runner resolves its own identity, queries a filtered task list, and chooses work under its own policy. Task responses include stable task and workspace IDs plus the project slug needed to leave a comment.
auth="Authorization: Bearer $VTRIV_AGENT_KEY"
curl -s -H "$auth" https://app.vtriv.com/api/me
curl -s -H "$auth" 'https://app.vtriv.com/api/tasks?assignee=me&runnable=1'
curl -s -X PATCH -H "$auth" -H "Content-Type: application/json"
https://app.vtriv.com/api/tasks/TASK_ID --data '{"status":"in_progress"}'
curl -s -X POST -H "$auth" -H "Content-Type: application/json"
https://app.vtriv.com/api/workspaces/WORKSPACE_ID/projects/PROJECT_SLUG/tasks/TASK_ID/comments
--data '{"body":"Completed the migration and saved the recovery steps."}'
curl -s -X PATCH -H "$auth" -H "Content-Type: application/json"
https://app.vtriv.com/api/tasks/TASK_ID --data '{"status":"done"}'
If a finished task needs a follow-up, add a comment withreopen: true. vtriv records the task as awaiting that agent. A runner may include that recorded follow-up in its own task query; an agent-authenticated comment clears the state.
The public REST API reference covers every field, filter, and response shape.