Ask the assistant

POST

/api/assistant/chats/{chatId}/messages

curl --request POST \
  --url http://localhost:3000/api/assistant/chats/0199e8b0-5a10-7a01-8b00-00000000002b/messages \
  --header 'Content-Type: application/json' \
  --cookie merran.session_token=<merran.session_token> \
  --data '{ "text": "Is this thick enough?", "files": [ { "id": "4f1c2a9e7b3d5f6a8c0e1b2d", "name": "sauce.jpg" } ], "context": { "recipe": "0199e8b0-5a10-7a01-8b00-000000000006" } }'

• Your Merran

Sends a message, and streams the assistant’s answer back as AI SDK’s UI message stream (server-sent events), the way useChat reads it: its text, and the tools it uses as it uses them. It can see photos and PDFs sent with a message (uploaded first, with POST /assistant/files) when the model reads them, drafting a recipe from one, look things up in the household’s recipes, plan, list and pantry, search the web when the model can, and propose changes, which come back as suggestions (GET /proposals/{proposalId}) for the person to apply. Both messages are kept. Uses the household’s model for the assistant, which must be able to use tools, and counts towards its AI spend. With an API key, it needs the assistant: write permission.

Authorizations

• session
• apiKey

Parameters

Path Parameters

chatId

required

string

Example

0199e8b0-5a10-7a01-8b00-00000000002b

Request Body^required

Media typeapplication/json

object

text

What they say. Can be left out with files.

string

"" <= 4000 characters

files

Photos and PDFs to send with it, up to 4, by the ids POST /assistant/files gave them: a photo of what they’re cooking, or a recipe to draft. The message keeps them as file parts, linking to each file.

Array<object>

<= 4 items

object

id

required

string

/^[a-f0-9]{24}$/

name

Its name, to show and to tell the model: “lasagna.pdf”.

string

<= 200 characters

context

What’s on their screen, for the assistant to know: “this recipe” is the one there.

object

recipe

The recipe on their screen, by id or address.

string

week

The first day of the week of the plan on their screen.

string

Example

{
  "text": "Is this thick enough?",
  "files": [
    {
      "id": "4f1c2a9e7b3d5f6a8c0e1b2d",
      "name": "sauce.jpg"
    }
  ],
  "context": {
    "recipe": "0199e8b0-5a10-7a01-8b00-000000000006"
  }
}

Responses

200

The answer, as it comes.

Media typetext/event-stream

AI SDK’s UI message stream.

string

401

Not signed in.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}

403

Not allowed.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}

404

No such chat of yours, or no such file.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}

422

The model can’t use tools, or read photos or PDFs.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}

429

This month’s AI limit is reached.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}