Import conversations

This guide shows how to send a conversation between a user and an assistant with POST /v1/memories/import. Alvia reads the turns in order and forms memories from the facts in the user’s turns; the assistant’s turns give them context. Use it at the end of a chat session, or to bring past conversations into Alvia.

For endpoint schemas and status codes, use the API reference.

Import one conversation

curl https://api.alvia.ai/v1/memories/import \
  -H "Authorization: Bearer $ALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "occurred_at": "2026-10-02T11:15:00-07:00",
    "scope": { "organization_id": "acme", "user_id": "u_4821" },
    "messages": [
      {
        "role": "user",
        "content": "We moved to the Enterprise plan yesterday."
      },
      {
        "role": "assistant",
        "content": "Got it. Where should invoices go now?"
      },
      {
        "role": "user",
        "content": "Send invoices to ap@acme.example from now on."
      }
    ]
  }'

1
import os
2
import requests
3

4
API_KEY = os.environ["ALVIA_API_KEY"]
5

6
conversation = [
7
    {
8
        "role": "user",
9
        "content": "We moved to the Enterprise plan yesterday.",
10
    },
11
    {
12
        "role": "assistant",
13
        "content": "Got it. Where should invoices go now?",
14
    },
15
    {
16
        "role": "user",
17
        "content": "Send invoices to ap@acme.example from now on.",
18
    },
19
]
20

21
response = requests.post(
22
    "https://api.alvia.ai/v1/memories/import",
23
    headers={"Authorization": f"Bearer {API_KEY}"},
24
    json={
25
        "occurred_at": "2026-10-02T11:15:00-07:00",
26
        "scope": {"organization_id": "acme", "user_id": "u_4821"},
27
        "messages": conversation,
28
    },
29
    timeout=30,
30
)
31
response.raise_for_status()  # 202 Accepted, empty body

1
const conversation = [
2
  {
3
    role: "user",
4
    content: "We moved to the Enterprise plan yesterday.",
5
  },
6
  {
7
    role: "assistant",
8
    content: "Got it. Where should invoices go now?",
9
  },
10
  {
11
    role: "user",
12
    content: "Send invoices to ap@acme.example from now on.",
13
  },
14
];
15

16
const response = await fetch(
17
  "https://api.alvia.ai/v1/memories/import",
18
  {
19
    method: "POST",
20
    headers: {
21
      Authorization: `Bearer ${process.env.ALVIA_API_KEY}`,
22
      "Content-Type": "application/json",
23
    },
24
    body: JSON.stringify({
25
      occurred_at: "2026-10-02T11:15:00-07:00",
26
      scope: { organization_id: "acme", user_id: "u_4821" },
27
      messages: conversation,
28
    }),
29
  },
30
);
31
// 202 Accepted, empty body
32
if (!response.ok) {
33
  throw new Error(`${response.status}: ${await response.text()}`);
34
}

1
package main
2

3
import (
4
  "bytes"
5
  "encoding/json"
6
  "io"
7
  "log"
8
  "net/http"
9
  "os"
10
  "time"
11
)
12

13
type message struct {
14
  Role    string `json:"role"`
15
  Content string `json:"content"`
16
}
17

18
func main() {
19
  conversation := []message{
20
    {
21
      Role:    "user",
22
      Content: "We moved to the Enterprise plan yesterday.",
23
    },
24
    {
25
      Role:    "assistant",
26
      Content: "Got it. Where should invoices go now?",
27
    },
28
    {
29
      Role:    "user",
30
      Content: "Send invoices to ap@acme.example from now on.",
31
    },
32
  }
33
  payload, err := json.Marshal(map[string]any{
34
    "occurred_at": "2026-10-02T11:15:00-07:00",
35
    "scope": map[string]string{
36
      "organization_id": "acme",
37
      "user_id":         "u_4821",
38
    },
39
    "messages": conversation,
40
  })
41
  if err != nil {
42
    log.Fatal(err)
43
  }
44
  req, err := http.NewRequest(http.MethodPost,
45
    "https://api.alvia.ai/v1/memories/import",
46
    bytes.NewReader(payload))
47
  if err != nil {
48
    log.Fatal(err)
49
  }
50
  key := os.Getenv("ALVIA_API_KEY")
51
  req.Header.Set("Authorization", "Bearer "+key)
52
  req.Header.Set("Content-Type", "application/json")
53

54
  client := &http.Client{Timeout: 30 * time.Second}
55
  resp, err := client.Do(req)
56
  if err != nil {
57
    log.Fatal(err)
58
  }
59
  defer resp.Body.Close()
60
  // 202 Accepted, empty body
61
  if resp.StatusCode != http.StatusAccepted {
62
    body, _ := io.ReadAll(resp.Body)
63
    log.Fatalf("%s: %s", resp.Status, body)
64
  }
65
}

1
using System.Net.Http.Json;
2

3
var key = Environment.GetEnvironmentVariable("ALVIA_API_KEY");
4
using var http = new HttpClient();
5
http.Timeout = TimeSpan.FromSeconds(30);
6
http.DefaultRequestHeaders.Authorization = new("Bearer", key);
7

8
var conversation = new[]
9
{
10
    new
11
    {
12
        role = "user",
13
        content = "We moved to the Enterprise plan yesterday.",
14
    },
15
    new
16
    {
17
        role = "assistant",
18
        content = "Got it. Where should invoices go now?",
19
    },
20
    new
21
    {
22
        role = "user",
23
        content = "Send invoices to ap@acme.example from now on.",
24
    },
25
};
26

27
var response = await http.PostAsJsonAsync(
28
    "https://api.alvia.ai/v1/memories/import",
29
    new
30
    {
31
        occurred_at = "2026-10-02T11:15:00-07:00",
32
        scope = new { organization_id = "acme", user_id = "u_4821" },
33
        messages = conversation,
34
    });
35
response.EnsureSuccessStatusCode(); // 202 Accepted, empty body

Because occurred_at is October 2 in the user’s time zone, “yesterday” resolves to October 1, 2026.

Prepare the messages

Send the user and assistant turns. Import takes the conversation itself, so leave out system, developer and tool turns.
Keep the turns in order. Alvia reads them as one conversation.
Import one conversation per request. The occurred_at date anchors every relative date in the conversation, so two chats from different days need two requests.
Name other speakers. Alvia reads a user turn without speaker as the words of the person the memories are about, and its memories keep the first person: the example above can form “We moved to the Enterprise plan yesterday (October 1, 2026).” Set speaker to a name, such as "Dana Reyes", when someone else said it. Write other memories in that scope in the same voice, so a new fact reads like the memory it changes.

Request fields

Field	Required	Description
`messages`	Yes	1 to 500 turns, in order.
`messages[].role`	Yes	`user` or `assistant`.
`messages[].content`	Yes	1 to 16,000 characters, with no run of more than 2,000 characters without a space.
`messages[].speaker`	No	Who said the turn, when it is not the person the memories are about. 1 to 128 characters, on one line, not starting with a space.
`occurred_at`	Yes	When the conversation took place. See Point-in-Time Reasoning and change over time.
`scope`	No	Who or what the memories are about. See Projects and scope.

All messages together can hold up to 320,000 characters. Very long conversations import best split into sessions: send each as its own request.

Response

A successful import returns 202 with an empty body. The memories become readable once formation finishes, in less than a minute; see Accepted means queued for formation and Read memories.

Cost

Alvia splits a long conversation into chunks. Each chunk uses one write from your monthly allowance, and each fact formed from a chunk uses one more. See Limits and allowances.

When the write allowance runs out partway through an import, Alvia imports the chunks that fit, in order, and still returns 202; the chunks past the allowance are not imported. The response does not say which part of the conversation was left out, so you cannot resume from where it stopped. Check the remaining allowance in the dashboard before a large import, and send long histories in smaller imports that your application tracks.

Retries

Validation is all-or-nothing: a request with an invalid turn returns 400 and imports nothing, so a fixed request imports cleanly. Do not retry a 400 unchanged.
Retry only requests that failed: network errors, 5xx responses and 429 responses, after the wait in Retry-After. A 202 means Alvia accepted the import, so do not send it again. When you retry, send the same messages and occurred_at. Each accepted request uses writes. See Retries in Store memories.

Errors

Error	Cause
`400` `validation_error`	A field breaks a rule. `errors` names it, such as `messages[2].role`.
`400` `invalid_argument` `message_too_large_to_process`	One message is too large to process. Shorten it.
`400` `invalid_argument` `conversation_too_large_to_process`	The conversation is too large for one request. Split it.
`401` `unauthorized`	The API key is missing or not valid.
`404` `not_found`	The project’s deletion started while the request was in progress.
`409` `conflict` `memory_limit_reached`	The account holds its plan’s stored-memory limit.
`429` `rate_limit_exceeded`	Too many requests per second.
`429` `rate_limit_exceeded` `monthly_write_quota_reached`	The monthly write allowance is used up.

See Errors for every code.

Filter sensitive information before imports

Set the project’s memory policy before the import, with keyword exclusions and a meaning rule for PII or health disclosures that your application must not remember. See Filter memories. A policy controls what becomes memory, not what reaches Alvia; see Memory policies. Alvia keeps the conversation’s text for the life of the project, and deleting the project erases it along with every memory; see Data retention and deletion in Security.

Use the conversation’s original occurred_at for historical imports, so its facts keep their real age. See Age and temporal decay.