API reference

Workflows

A workflow is a reusable agent configuration. These endpoints let you list, create, and retrieve workflows scoped to the API key's account.

The workflow object#

idstringoptional

Unique identifier for the workflow.

namestringoptional

Human-readable name, 1–120 characters.

descriptionstring | nulloptional

Optional description, up to 500 characters.

statusstringoptional

Either active or paused. Runs cannot be triggered on a paused workflow.

modelstringoptional

Default model used by agents that don't set their own, e.g. claude-sonnet-4-6 or gpt-5.4. Any catalog model from any provider; see Models.

crewAgent[]optional

The ordered list of agents (1–10). Each agent has role, systemPrompt, and an optional model.

memory_enabledbooleanoptional

Whether each agent keeps persistent memory between runs. Default false.

created_atstringoptional

ISO 8601 timestamp of creation.

updated_atstringoptional

ISO 8601 timestamp of the last update. Returned on list and retrieve (not on the create response).

List workflows#

GET/v1/workflows

Returns every workflow owned by the authenticated account, most recently updated first. Takes no parameters.

Request

bash

curl https://loopllama.ai/api/v1/workflows \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY"

Response

json

{
  "data": [
    {
      "id": "ckv9...",
      "name": "Brief writer",
      "description": null,
      "status": "active",
      "model": "claude-sonnet-4-6",
      "crew": [
        { "role": "planner", "systemPrompt": "You are a planning agent..." },
        { "role": "writer",  "systemPrompt": "You are a writing agent..." }
      ],
      "created_at": "2026-05-20T17:00:00.000Z",
      "updated_at": "2026-05-20T17:00:00.000Z"
    }
  ]
}

Create a workflow#

POST/v1/workflows

Creates a new workflow. If crew is omitted, the default planner→writer crew is used. Responds with 201 Created.

Body parameters

namestringrequired

Workflow name, 1–120 characters.

descriptionstringoptional

Optional description, up to 500 characters.

modelstringoptional

Optional default model, up to 80 characters — any id from the model catalog, optionally prefixed with its provider (openai/gpt-5.4). Unroutable ids return 400. Defaults to the server's configured model (claude-sonnet-4-6).

crewAgent[]optional

Optional array of 1–10 agents. Each agent requires role (1–60 chars) and systemPrompt (1–8000 chars), with an optional model.

memory_enabledbooleanoptional

Give every agent persistent memory across runs. Default false.

Request

bash

curl -X POST https://loopllama.ai/api/v1/workflows \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spec reviewer",
    "description": "Summarize specs and surface risks",
    "crew": [
      { "role": "researcher", "systemPrompt": "Extract key claims and open questions." },
      { "role": "writer", "systemPrompt": "Draft a one-page summary with a Risks section." }
    ]
  }'

Response

json

{
  "data": {
    "id": "ckva...",
    "name": "Spec reviewer",
    "description": "Summarize specs and surface risks",
    "status": "active",
    "model": "claude-sonnet-4-6",
    "crew": [
      { "role": "researcher", "systemPrompt": "Extract key claims and open questions." },
      { "role": "writer", "systemPrompt": "Draft a one-page summary with a Risks section." }
    ],
    "created_at": "2026-05-20T17:05:00.000Z"
  }
}

Retrieve a workflow#

GET/v1/workflows/{id}

Fetches a single workflow by id. Returns 404 Not found if the workflow doesn't exist or belongs to a different account.

Path parameters

idstringrequired

The workflow id.

Request

bash

curl https://loopllama.ai/api/v1/workflows/ckva... \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY"

Response

json

{
  "data": {
    "id": "ckva...",
    "name": "Spec reviewer",
    "description": "Summarize specs and surface risks",
    "status": "active",
    "model": "claude-sonnet-4-6",
    "crew": [ { "role": "researcher", "systemPrompt": "..." } ],
    "created_at": "2026-05-20T17:05:00.000Z",
    "updated_at": "2026-05-20T17:05:00.000Z"
  }
}

Triggers#

A trigger starts runs of a workflow when something happens, so the agents in it react on their own. Four types: webhook (an inbound POST to a private URL), gmail and outlook (one run per new email in the connected mailbox), and slack (one run per new human message in a channel). Runs started this way have trigger: "event". See how triggers work.

The trigger object

idstringoptional

Unique identifier.

typestringoptional

webhook, gmail, outlook or slack.

namestring | nulloptional

Optional label.

enabledbooleanoptional

Paused triggers never fire or poll.

configobjectoptional

instructions (prepended to every run input); query (gmail search); folder (outlook, default inbox); channel and mentionOnly (slack).

urlstring | nulloptional

Webhook only: the URL to POST to. It contains the secret — treat it like a password.

fireCountintegeroptional

Runs started so far.

lastFiredAtstring | nulloptional

When it last started a run.

lastRunIdstring | nulloptional

The most recent run it started.

lastErrorstring | nulloptional

The last poll or run failure, if any.

autoPauseAfterintegeroptional

Disable after this many consecutive failures (default 5, 0 = never).

disabledReasonstring | nulloptional

manual or auto_paused_failures.

List triggers

GET/v1/workflows/{id}/triggers

Create a trigger

POST/v1/workflows/{id}/triggers

typestringrequired

One of the four types.

namestringoptional

Optional label, up to 120 characters.

configobjectoptional

Per-type settings, see above. Slack requires channel.

enabledbooleanoptional

Default true.

autoPauseAfterintegeroptional

Default 5.

bash

curl -X POST https://loopllama.ai/api/v1/workflows/ckva.../triggers \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "gmail",
    "name": "Deals inbox",
    "config": {
      "query": "to:deals@yourco.com -category:promotions",
      "instructions": "A new email arrived in the deals inbox. Triage it, look the sender up in the CRM, and draft a reply for approval."
    }
  }'

For a webhook trigger the response includes url. POST any JSON, form or text body (up to 256 KB) to it and a run is queued; the response is 202 with run_id. Polling triggers check the mailbox or channel about once a minute and only react to messages that arrive after they were created — nothing is backfilled.

Update, pause or resume a trigger

PATCH/v1/workflows/{id}/triggers/{triggerId}

Any of name, enabled, config, autoPauseAfter, or rotateSecret: true to issue a webhook a new URL. Changing a polling trigger's config restarts it from "now".

Delete a trigger

DELETE/v1/workflows/{id}/triggers/{triggerId}

Run history is kept.

Follow-up tasks#

Work an agent has scheduled for itself (schedule_followup) or that you hand it. When dueAt arrives a run starts with the task as input; see how tasks work.

The task object

idstringoptional

Unique identifier.

rolestringoptional

The step that owns it.

agentIdstring | nulloptional

Set when that step is a team agent.

titlestringoptional

Up to 200 characters.

detailsstring | nulloptional

Instructions for the agent when it comes due, up to 4000 characters.

statusstringoptional

open, running, done, cancelled or failed.

dueAtstringoptional

ISO 8601. The tick starts the run within a minute of this.

sourcestringoptional

agent or operator.

createdByRunIdstring | nulloptional

The run whose agent scheduled it.

runIdstring | nulloptional

The run that executed it.

attemptsintegeroptional

Runs started for it so far (max 3).

List tasks

GET/v1/workflows/{id}/tasks

GET/v1/agents/{id}/tasks

Assign a task

POST/v1/workflows/{id}/tasks

titlestringrequired

1–200 characters.

detailsstringoptional

Optional.

dueAtstringoptional

ISO 8601. Provide this or dueInMinutes.

dueInMinutesintegeroptional

5 to 129600 (90 days).

rolestringoptional

Which step owns it. Defaults to the first step.

bash

curl -X POST https://loopllama.ai/api/v1/workflows/ckva.../tasks \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "account-manager",
    "title": "Check whether Acme signed the proposal",
    "details": "If not signed, send a friendly nudge to Dana Reyes and cc the AE.",
    "dueAt": "2026-10-09T14:00:00Z"
  }'

Update a task

PATCH/v1/workflows/{id}/tasks/{taskId}

title, details, dueAt, or status (open to reopen or run sooner, done, cancelled). A running task returns 409.

Delete a task

DELETE/v1/workflows/{id}/tasks/{taskId}

Agent memory#

When a workflow has memory_enabled, each agent (by crew role) keeps notes it chooses to remember and a system-written journal of its past runs. These endpoints let you read that memory, brief an agent before its next run, pin the notes it must always see, and delete anything wrong. See how memory works.

The memory object

idstringoptional

Unique identifier.

rolestringoptional

The crew role this memory belongs to.

kindstringoptional

note (a durable fact) or journal (what the agent did on one run).

contentstringoptional

The text, up to 2000 characters.

pinnedbooleanoptional

Pinned notes are always placed in the agent's prompt; others are included newest-first within a budget and searchable by the agent.

sourcestringoptional

agent (the agent wrote it), operator (written via dashboard or API), or system (journal).

runIdstring | nulloptional

The run that produced it, when applicable.

createdAtstringoptional

ISO 8601 timestamp.

List memory

GET/v1/workflows/{id}/memory

Pinned notes first, then newest first, up to 200 entries. Filter to one agent with ?role=.

bash

curl "https://loopllama.ai/api/v1/workflows/ckva.../memory?role=account-manager" \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY"

Add a note

POST/v1/workflows/{id}/memory

rolestringrequired

Which agent the note is for (must match a crew role).

contentstringrequired

The note, 1–2000 characters.

pinnedbooleanoptional

Always include it in the prompt. Default false.

bash

curl -X POST https://loopllama.ai/api/v1/workflows/ckva.../memory \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "account-manager",
    "content": "Acme Corp: main contact is Dana Reyes. They prefer a call before any pricing email.",
    "pinned": true
  }'

Update a note

PATCH/v1/workflows/{id}/memory/{memoryId}

Change content and/or pinned. Journal entries are read-only and return 400.

Delete a memory

DELETE/v1/workflows/{id}/memory/{memoryId}

Removes a note or journal entry. The agent will not see it again.