Get a conversation with Rigel

agent.conversation_get

GET/api/v1/households/{household_id}/agent/conversations/{conversation_id}

Route

One of your conversations with Rigel, with every message in it, oldest first.

Parameters#

Get a conversation with Rigel: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`conversation_id`pathstringrequired	The conversation's ID.

Response#

200 The conversation.

Get a conversation with Rigel: response fields
Field	Description
`id`stringrequired	The conversation's ID.
`title`string or nullrequired	A short name taken from the first message.
`created_at`integerrequired	When it started, UTC milliseconds.
`updated_at`integerrequired	When the last message was saved, UTC milliseconds.
`messages`array of objectsrequired	Its messages, oldest first.
`messages[].id`stringrequired	The message's ID.
`messages[].role`one of: person, rigelrequired	Who said it.
`messages[].text`stringrequired	What was said.
`messages[].file_ids`array of stringsrequired	Photos and files sent with a person's message.
`messages[].actions`array of objectsrequired	What Rigel did during the turn, in order. Empty for a person's message.
`messages[].actions[].tool`stringrequired	The tool, such as meals.plan.add_entry.
`messages[].actions[].summary`stringoptional	The command or query's summary, in plain words, such as "Put a card on the dashboard".
`messages[].actions[].kind`one of: command, query, ui_action, agent_toolrequired	No description.
`messages[].actions[].input`anyoptional	No description.
`messages[].actions[].outcome`one of: applied, rejected, answered, awaiting_confirmation, refused, failedrequired	No description.
`messages[].actions[].command_id`stringoptional	No description.
`messages[].actions[].result`anyoptional	No description.
`messages[].actions[].error`objectoptional
`messages[].actions[].error.code`stringrequired	No description.
`messages[].actions[].error.message`stringrequired	No description.
`messages[].pending`array of objectsrequired	Confirmations still waiting for your answer. Empty once answered or cancelled.
`messages[].pending[].id`stringrequired	Pass back to confirm or cancel it.
`messages[].pending[].command`stringrequired	No description.
`messages[].pending[].input`anyoptional	No description.
`messages[].pending[].description`stringrequired	What it will do, in plain words.
`messages[].stopped`one of: done, call_limit, over_budget, unavailable, cancelled, null or nullrequired	Why Rigel's turn ended early, or null if it finished.
`messages[].created_at`integerrequired	When it was said, UTC milliseconds.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Get a conversation with Rigel: errors
Status	Code	When
`401`	`unauthenticated`	The request has no valid session.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

Read a conversation with Rigel

Every message, oldest first, with what Rigel did while answering.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/agent/conversations/agc_01M6V9CTBYGRF0AY79C9HQH1M1' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/agent/conversations/agc_01M6V9CTBYGRF0AY79C9HQH1M1", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/agent/conversations/agc_01M6V9CTBYGRF0AY79C9HQH1M1 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTC3MJ8W8MGHH52KM4PQ

{
  "id": "agc_01M6V9CTBYGRF0AY79C9HQH1M1",
  "title": "What's for dinner on Monday?",
  "created_at": 1794064679148,
  "updated_at": 1794064685148,
  "messages": [
    {
      "id": "agm_01M6V9CTBYQGF608JKX7YMDGCG",
      "role": "person",
      "text": "What's for dinner on Monday?",
      "file_ids": [],
      "actions": [],
      "pending": [],
      "stopped": null,
      "created_at": 1794064679148
    },
    {
      "id": "agm_01M6V9CTC1V2FCFGQY1F672B2X",
      "role": "rigel",
      "text": "Monday is tomato and white bean orzo, about 30 minutes. It's planned for all four of you, with a note to make extra for lunches.",
      "file_ids": [],
      "actions": [
        {
          "tool": "meals.week.get",
          "summary": "The meal plan for a week",
          "kind": "query",
          "input": {
            "week_start": "2026-11-09"
          },
          "outcome": "answered"
        }
      ],
      "pending": [],
      "stopped": null,
      "created_at": 1794064679148
    },
    {
      "id": "agm_01M6V9CTC2FW7XF10F7Q4NM48Y",
      "role": "person",
      "text": "What do I need to buy for it?",
      "file_ids": [],
      "actions": [],
      "pending": [],
      "stopped": null,
      "created_at": 1794064685148
    },
    {
      "id": "agm_01M6V9CTC2FZARPK28NVW1SRBV",
      "role": "rigel",
      "text": "For the orzo you need crushed tomatoes and baby spinach. You already have olive oil and orzo, and the spinach is optional.",
      "file_ids": [],
      "actions": [
        {
          "tool": "recipes.recipe.shopping_preview",
          "summary": "What to buy to cook a recipe",
          "kind": "query",
          "input": {
            "recipe_id": "rcp_01M6V9CSD8VZYF11AC568Y7QPZ",
            "servings": 4
          },
          "outcome": "answered"
        }
      ],
      "pending": [],
      "stopped": null,
      "created_at": 1794064685148
    }
  ]
}

A conversation that doesn't exist

Another member's conversation looks the same, so one person can't tell whether the other has any.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/agent/conversations/agc_01JC0000000000000000000000' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/agent/conversations/agc_01JC0000000000000000000000", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/agent/conversations/agc_01JC0000000000000000000000 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01M6V9CTC4PBQWRFXET8DAEFVT

{
  "error": {
    "code": "not_found",
    "message": "That conversation wasn't found.",
    "details": {},
    "recovery": "Check the ID. You can only reach households you're a member of.",
    "request_id": "req_01M6V9CTC4PBQWRFXET8DAEFVT"
  }
}