Fryri API reference

Quickstart

Make your first call from your server. Then use the same thread for a follow-up or stream a run to show progress in your app. The booking app guide shows how to connect your own actions and ask for approval.

1. Create a key in the developer console. A newly verified account starts with $1 of credit. Export the key as FRYRI_API_KEY:

   export FRYRI_API_KEY="fryri_sk_..."

2. Start a run. Omit thread_id to start a new conversation. The call waits up to 55 seconds. If it returns 202, follow the run's events or check its status before using the reply.

   curl -X POST https://api.fryri.com/v1/runs \
     -H "Authorization: Bearer $FRYRI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "message": "Suggest three beginner classes for someone getting back into exercise, and say why in one line each.",
       "end_user_id": "member_812"
     }'

   {
     "id": "run_b72d5e0a19c48f36d2a0e7c1",
     "thread_id": "thr_3e0b7c94d1a26f58c0e4b9a7",
     "end_user_id": "member_812",
     "status": "done",
     "reply": "1. **Gentle yoga**: it rebuilds mobility without strain.\n2. **Beginner spin**: you set the resistance, so the effort stays yours.\n3. **Low-impact circuit**: short stations build strength with rests in between.",
     "sources": [],
     "files": [],
     "error": null,
     "cost_usd": 0.016558,
     "created_at": "2026-11-07T09:02:11.540218Z",
     "finished_at": "2026-11-07T09:02:19.007431Z"
   }

3. To continue the conversation, send the returned thread_id with the user's next message once the first run has finished. Replace the example thread ID with your own.

   curl -X POST https://api.fryri.com/v1/runs \
     -H "Authorization: Bearer $FRYRI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "message": "Which of those suits a sore knee?",
       "end_user_id": "member_812",
       "thread_id": "thr_3e0b7c94d1a26f58c0e4b9a7"
     }'

4. Set stream to true to receive server-sent events with progress and reply text.

   curl -N -X POST https://api.fryri.com/v1/runs \
     -H "Authorization: Bearer $FRYRI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"message": "Find the opening hours of the city pool this week.", "end_user_id": "member_812", "stream": true}'

Complete example

Python, with the Python client (one file, no dependencies):

from fryri import Fryri

fryri = Fryri()  # reads FRYRI_API_KEY
USER = "member_812"

# Send request
run = fryri.runs.create(
    message="Suggest three beginner classes for someone getting back into exercise.",
    end_user_id=USER,
)
run = fryri.runs.wait(run["id"])

# Continue the thread
follow_up = fryri.runs.create(
    message="Which of those suits a sore knee?",
    thread_id=run["thread_id"],
    end_user_id=USER,
)

# Read response
print(run["reply"])
print(fryri.runs.wait(follow_up["id"])["reply"])

TypeScript on Node 18 or later, with the TypeScript client. Save both files side by side and run npx tsx quickstart.mts:

import { Fryri } from "./fryri.ts";

const fryri = new Fryri(); // reads FRYRI_API_KEY
const USER = "member_812";

// Send request
let run = await fryri.runs.create({
  message: "Suggest three beginner classes for someone getting back into exercise.",
  end_user_id: USER,
});
run = await fryri.runs.wait(run.id);

// Stream the follow-up as it is written
for await (const event of fryri.runs.stream({
  message: "Which of those suits a sore knee?",
  thread_id: run.thread_id,
  end_user_id: USER,
})) {
  if (event.type === "text") process.stdout.write(event.delta ?? "");
}

Both clients are single files with no dependencies. They cover every call on this page, follow a stream across dropped connections and verify webhook signatures. The OpenAPI spec at https://api.fryri.com/v1/openapi.json describes every call on this page, for a client of your own. https://api.fryri.com/v1/docs lets you try each call in the browser.

Authentication

An API key authenticates every request. Create keys in the developer console, which shows each key once. Send the key as a Bearer token:

Authorization: Bearer $FRYRI_API_KEY

A missing, revoked or mistyped key fails with 401 unauthorized. A key works on the library of its own account and on the end users of that account. It's recommended to keep keys on your server, in an environment variable such as FRYRI_API_KEY.

Credit

Calls spend from the account's prepaid credit, separate from any Fryri plan. A newly verified account starts with $1 of credit. Starting a run and every memory, search, answer and end-user call need credit, including the free ones. Reading, following, answering and stopping a run, threads, actions, webhooks and a retained answer work without it. Without credit, a call that needs it fails with 402 insufficient_credits. Top-ups, spend caps per key, usage and the request log are in the developer console. Pricing lists what each call costs.

Rate limits

Each key has a limit of 240 requests per minute, the same on every plan.

A request over the limit fails with 429 rate_limited. Its Retry-After header gives the seconds to wait before the next try. Requests with a missing or invalid key have a separate limit: after 100 of them in one minute from one client, the next requests from that client also fail with 429 until the minute ends.

Request IDs

Every response carries an X-Request-ID header, and an error body repeats it as request_id. It's recommended to log it and quote it when you contact support.

The run object

Start, get, respond and stop return the same run object:

POST /v1/runs

POST /v1/runs starts the agent on a job. A run without thread_id starts a new thread, and a run with one continues that conversation. A thread runs one run at a time.

Without stream, the call waits up to 55 seconds. A run that settled returns 200. A run still working, or waiting for your app, returns 202: follow it with events, a webhook or get. The run keeps working if your connection drops. Every response carries the X-Fryri-Run-Id and X-Fryri-Thread-Id headers.

A run bills what its model and tools use, the same as the same job in the Fryri app, and cost_usd is what it charged. Web tools have listed prices. A run with thread_id while another run in that thread works fails with 409 thread_busy. An account runs up to 100 runs at once; the next one fails with 429 too_many_runs.

Request

curl -X POST https://api.fryri.com/v1/runs \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "When did I last miss a class, and can I bring a guest to Thursday'\''s 6pm spin? Book me in if so.",
    "end_user_id": "member_812"
  }'

Response 202

{
  "id": "run_5f0c2a9e41d87b3c6e20f914",
  "thread_id": "thr_8a31d07c5be24f96a1e0c3d2",
  "end_user_id": "member_812",
  "status": "needs_app",
  "reply": null,
  "sources": [],
  "files": [],
  "error": null,
  "cost_usd": null,
  "created_at": "2026-11-07T09:14:02.118407Z",
  "finished_at": null
}

GET /v1/runs/{run_id}

GET /v1/runs/{run_id} returns the run object: its status and, once it settled, its reply, sources and files. The run id is enough: a run belongs to your account, so a webhook handler that holds only the id can read it. end_user_id is optional on every call that names a run; when you pass it, it must be the run's own, or the call returns 404. Reading a run is free.

Request

curl "https://api.fryri.com/v1/runs/run_5f0c2a9e41d87b3c6e20f914" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

Response

{
  "id": "run_5f0c2a9e41d87b3c6e20f914",
  "thread_id": "thr_8a31d07c5be24f96a1e0c3d2",
  "end_user_id": "member_812",
  "status": "done",
  "reply": "You last missed a class on 28 October (Tuesday 7am yoga). Members can bring one guest a month to any class, so I booked you and a guest into Thursday's 6pm spin. [1]",
  "sources": [
    {
      "type": "document",
      "id": "file_Qm81vTzKc0aR2wLb",
      "title": "Guest policy",
      "url": null,
      "text": "Members may bring one guest per calendar month to any class. Guests sign the waiver at the front desk...",
      "text_truncated": true,
      "source_ref": "policies/guests.md",
      "location": {
        "line_start": 3,
        "line_end": 5
      },
      "citation": 1,
      "cited": true,
      "library": "shared"
    }
  ],
  "files": [],
  "error": null,
  "cost_usd": 0.016558,
  "created_at": "2026-11-07T09:14:02.118407Z",
  "finished_at": "2026-11-07T09:15:41.902733Z"
}

GET /v1/runs/{run_id}/events

GET /v1/runs/{run_id}/events streams the events of a run as text/event-stream, from the start or after a given seq. A POST /v1/runs with stream: true answers with the same events. Each event is an id: line and one data: line that holds a JSON object with seq and type:

The stream ends after done or error. The reply in done is final, so it replaces the joined text. While a request waits for your app, the run has the status needs_app and the stream stays open; the events go on after you respond. Lines that start with : are heartbeats. Events are kept, so a dropped connection reconnects with after set to the last seq it received, or with the standard Last-Event-ID header, and misses nothing. Following a run is free.

Request

curl -N "https://api.fryri.com/v1/runs/run_5f0c2a9e41d87b3c6e20f914/events" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

Response

id: 1
data: {"seq":1,"type":"progress","step":"step_1","status":"started","label":"Searching the library"}

id: 2
data: {"seq":2,"type":"progress","step":"step_1","status":"finished","label":"Searching the library","outcome":"succeeded","targets":[{"kind":"document","label":"Guest policy"}]}

id: 3
data: {"seq":3,"type":"action_request","request_id":"req_91b0e4d27c3a58f6b2d0e817","expires_at":"2026-11-07T09:29:05.664120Z","action":"find_bookings","input":{"from":"2026-10-01"}}

id: 4
data: {"seq":4,"type":"approval_request","request_id":"req_2c7e91f04ab35d68e0f1a9c4","expires_at":"2026-11-08T09:14:19.250981Z","action":"book_class","input":{"class_id":"spin_thu_1800","guests":1},"description":"Book the member into a class, with up to one guest."}

id: 5
data: {"seq":5,"type":"action_request","request_id":"req_d4e6a0b37f91c25e8a0b6c31","expires_at":"2026-11-07T09:30:37.118544Z","action":"book_class","input":{"class_id":"spin_thu_1800","guests":1}}

id: 6
data: {"seq":6,"type":"text","delta":"You last missed a class on 28 October (Tuesday 7am yoga). "}

id: 7
data: {"seq":7,"type":"text","delta":"Members can bring one guest a month to any class, so I booked you and a guest into Thursday's 6pm spin."}

id: 8
data: {"seq":8,"type":"done","run":{"id":"run_5f0c2a9e41d87b3c6e20f914","thread_id":"thr_8a31d07c5be24f96a1e0c3d2","end_user_id":"member_812","status":"done","reply":"You last missed a class on 28 October (Tuesday 7am yoga). Members can bring one guest a month to any class, so I booked you and a guest into Thursday's 6pm spin. [1]","sources":[{"type":"document","id":"file_Qm81vTzKc0aR2wLb","title":"Guest policy","url":null,"text":"Members may bring one guest per calendar month to any class. Guests sign the waiver at the front desk...","text_truncated":true,"source_ref":"policies/guests.md","location":{"line_start":3,"line_end":5},"citation":1,"cited":true,"library":"shared"}],"files":[],"error":null,"cost_usd":0.016558,"created_at":"2026-11-07T09:14:02.118407Z","finished_at":"2026-11-07T09:15:41.902733Z"}}

POST /v1/runs/{run_id}/respond

POST /v1/runs/{run_id}/respond answers what a run paused for, and the run carries on. One call answers all three kinds of request, each with its own field:

Every respond carries the request_id of the event. Answering the same request_id again with the same answer changes nothing. A different answer fails with 409 request_answered, and an answer of the wrong kind with 422 wrong_answer_kind. An action_request left unanswered expires after 15 minutes, and an approval or a question after 24 hours: the call settles as failed and the run replies without it. Like POST /v1/runs, the call waits up to 55 seconds and returns the run: 200 once it settled, else 202. Responding is free; the run bills its own work.

Request: an action's result

curl -X POST https://api.fryri.com/v1/runs/run_5f0c2a9e41d87b3c6e20f914/respond \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req_91b0e4d27c3a58f6b2d0e817",
    "result": {
      "bookings": [
        {
          "class": "Yoga, Tuesday 7am",
          "date": "2026-10-28",
          "attended": false
        },
        {
          "class": "Spin, Thursday 6pm",
          "date": "2026-10-30",
          "attended": true
        }
      ]
    }
  }'

Request: an approval

curl -X POST https://api.fryri.com/v1/runs/run_5f0c2a9e41d87b3c6e20f914/respond \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req_2c7e91f04ab35d68e0f1a9c4",
    "decision": "approve"
  }'

Response 202

{
  "id": "run_5f0c2a9e41d87b3c6e20f914",
  "thread_id": "thr_8a31d07c5be24f96a1e0c3d2",
  "end_user_id": "member_812",
  "status": "needs_app",
  "reply": null,
  "sources": [],
  "files": [],
  "error": null,
  "cost_usd": null,
  "created_at": "2026-11-07T09:14:02.118407Z",
  "finished_at": null
}

POST /v1/runs/{run_id}/stop

POST /v1/runs/{run_id}/stop stops a run, including the step it is taking and a request waiting for your app. The run settles as stopped and keeps the reply it had written. Stopping a run that already settled returns it unchanged. The call waits up to 10 seconds for the run to settle and returns 200, or 202 while the stop is on its way. The body can be empty; an end_user_id in it must be the run's own. Stopping is free.

Request

curl -X POST https://api.fryri.com/v1/runs/run_5f0c2a9e41d87b3c6e20f914/stop \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "id": "run_5f0c2a9e41d87b3c6e20f914",
  "thread_id": "thr_8a31d07c5be24f96a1e0c3d2",
  "end_user_id": "member_812",
  "status": "stopped",
  "reply": "You last missed a class on 28 October.",
  "sources": [],
  "files": [],
  "error": null,
  "cost_usd": 0.016558,
  "created_at": "2026-11-07T09:14:02.118407Z",
  "finished_at": "2026-11-07T09:14:33.507112Z"
}

Run errors

A failed run carries one of these in error.code:

PUT /v1/actions

PUT /v1/actions sets the actions your app offers the agent, replacing the whole list, and GET /v1/actions reads it back. Every run of your account, your end users' runs included, can call them. A run calls an action by pausing with an action_request: your app runs its own code and sends the result to POST /v1/runs/{run_id}/respond. Fryri calls no address of yours, so an action works for any app, including one with no public API.

A run that is already working uses the new list from its next call. A call to an action the new list drops does not reach your app. Setting and reading actions is free.

Request

curl -X PUT https://api.fryri.com/v1/actions \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {
        "name": "find_bookings",
        "description": "List the member'\''s class bookings and attendance between two dates.",
        "input": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "format": "date"
            },
            "to": {
              "type": "string",
              "format": "date"
            }
          },
          "required": [
            "from"
          ]
        },
        "needs_approval": false
      },
      {
        "name": "book_class",
        "description": "Book the member into a class, with up to one guest.",
        "input": {
          "type": "object",
          "properties": {
            "class_id": {
              "type": "string"
            },
            "guests": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1
            }
          },
          "required": [
            "class_id"
          ]
        },
        "needs_approval": true
      }
    ]
  }'

Response

{
  "actions": [
    {
      "name": "find_bookings",
      "description": "List the member's class bookings and attendance between two dates.",
      "input": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "format": "date"
          },
          "to": {
            "type": "string",
            "format": "date"
          }
        },
        "required": [
          "from"
        ]
      },
      "needs_approval": false
    },
    {
      "name": "book_class",
      "description": "Book the member into a class, with up to one guest.",
      "input": {
        "type": "object",
        "properties": {
          "class_id": {
            "type": "string"
          },
          "guests": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1
          }
        },
        "required": [
          "class_id"
        ]
      },
      "needs_approval": true
    }
  ]
}

POST /v1/webhooks

POST /v1/webhooks registers an https address that Fryri sends a POST to when a run of your account needs your app or settles. A webhook suits an app that cannot hold a stream open while a person decides. GET /v1/webhooks lists them without their secrets, and DELETE /v1/webhooks/{webhook_id} deletes one. An account has up to 10 webhooks. Webhooks are free.

The response carries the secret that signs every delivery. It is shown only in this response, so store it. enabled turns false after 8 failed deliveries in a row; register the address again to start over.

Request

curl -X POST https://api.fryri.com/v1/webhooks \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://gym.example.com/fryri/webhook"
  }'

Response

{
  "id": "wh_14",
  "url": "https://gym.example.com/fryri/webhook",
  "events": [
    "run.needs_app",
    "run.done",
    "run.failed",
    "run.stopped"
  ],
  "enabled": true,
  "created_at": "2026-11-07T09:10:12.004571Z",
  "last_success_at": null,
  "last_failure_at": null,
  "secret": "whsec_****"
}

Deliveries

Each delivery is a JSON body with id, type, created_at and data. data holds run_id, thread_id, end_user_id and status, and for run.needs_app the open request with its id, kind (action, approval or question) and action. A delivery never carries the reply or what anyone wrote: read those with GET /v1/runs/{run_id} and its events.

Delivery

{
  "id": "evt_5821",
  "type": "run.needs_app",
  "created_at": "2026-11-07T09:14:19.251377Z",
  "data": {
    "run_id": "run_5f0c2a9e41d87b3c6e20f914",
    "thread_id": "thr_8a31d07c5be24f96a1e0c3d2",
    "end_user_id": "member_812",
    "status": "needs_app",
    "request": {
      "id": "req_2c7e91f04ab35d68e0f1a9c4",
      "kind": "approval",
      "action": "book_class"
    }
  }
}

The Fryri-Signature header reads t={unix seconds},v1={hex}, where v1 is the HMAC-SHA256 of {t}.{raw body} keyed with the secret. Verify it against the raw bytes before parsing, and reject a t far from now. Answer with a 2xx within 5 seconds. Any other answer is retried after 1, 5, 15, 60 and 240 minutes.

Verify a delivery

Python:

import hashlib
import hmac
import time


def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

TypeScript on Node 18 or later:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, header: string, secret: string, toleranceSec = 300): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((part) => [part.slice(0, part.indexOf("=")), part.slice(part.indexOf("=") + 1)]),
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  const given = String(parts.v1 ?? "");
  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

List webhooks

curl "https://api.fryri.com/v1/webhooks" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

{
  "webhooks": [
    {
      "id": "wh_14",
      "url": "https://gym.example.com/fryri/webhook",
      "events": [
        "run.needs_app",
        "run.done",
        "run.failed",
        "run.stopped"
      ],
      "enabled": true,
      "created_at": "2026-11-07T09:10:12.004571Z",
      "last_success_at": "2026-11-07T09:15:42.311204Z",
      "last_failure_at": null
    }
  ]
}

Delete a webhook

curl -X DELETE "https://api.fryri.com/v1/webhooks/wh_14" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

{
  "id": "wh_14",
  "deleted": true
}

GET /v1/threads

A thread is one ongoing conversation, and every run happens in one. The agent remembers what was said in a thread. GET /v1/threads lists threads, most recently used first, paged with next_cursor. GET /v1/threads/{thread_id} returns one thread with up to its 200 newest messages, oldest first. Set end_user_id to list one of your end users' threads. A thread id alone finds that thread, whichever end user it belongs to; an end_user_id passed with it must be the thread's own, or the call returns 404. Reading threads is free.

List threads

curl "https://api.fryri.com/v1/threads?end_user_id=member_812&limit=20" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

{
  "threads": [
    {
      "id": "thr_8a31d07c5be24f96a1e0c3d2",
      "end_user_id": "member_812",
      "title": "Missed classes and a guest pass",
      "created_at": "2026-11-07T09:14:02.110925Z",
      "updated_at": "2026-11-07T09:15:41.902733Z"
    }
  ],
  "next_cursor": null
}

Get a thread

curl "https://api.fryri.com/v1/threads/thr_8a31d07c5be24f96a1e0c3d2" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

{
  "id": "thr_8a31d07c5be24f96a1e0c3d2",
  "end_user_id": "member_812",
  "title": "Missed classes and a guest pass",
  "created_at": "2026-11-07T09:14:02.110925Z",
  "updated_at": "2026-11-07T09:15:41.902733Z",
  "messages": [
    {
      "role": "user",
      "text": "When did I last miss a class, and can I bring a guest to Thursday's 6pm spin? Book me in if so.",
      "created_at": "2026-11-07T09:14:02.131760Z"
    },
    {
      "role": "assistant",
      "text": "You last missed a class on 28 October (Tuesday 7am yoga). Members can bring one guest a month to any class, so I booked you and a guest into Thursday's 6pm spin.",
      "created_at": "2026-11-07T09:15:41.880214Z"
    }
  ]
}

DELETE /v1/threads/{thread_id} deletes a thread: a run still working in it stops, its messages and run results are deleted, and what the agent learned from it is forgotten with it. Deleting is free.

Delete a thread

curl -X DELETE "https://api.fryri.com/v1/threads/thr_8a31d07c5be24f96a1e0c3d2" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

{
  "id": "thr_8a31d07c5be24f96a1e0c3d2",
  "deleted": true
}

The memory object

Add, list and get return the same memory object:

status and status_reason go together as follows:

POST /v1/memories

POST /v1/memories adds a note, document or conversation snapshot. The memory comes back at once with the status processing, and search finds it once it is ready. A short note is usually ready within seconds. A long document, or a large batch added at once, can take a few minutes.

Send exactly one of text, file or messages as JSON, or upload a file as multipart/form-data. A JSON body must carry exactly one of the three. Otherwise, the request fails with 422 invalid_request.

JSON body

messages is a JSON array of 1 to 200 turns. Each turn has role (user or assistant), nonblank content and optional created_at with a time zone. Array order is authoritative. The rendered transcript, including turn headings, must fit within 30,000 characters. Send a complete updated snapshot with the same source_ref to replace an earlier one. See Conversation snapshots.

Multipart form fields

Header

It's recommended to send an Idempotency-Key with every add, so a retry after a dropped connection never adds the memory twice.

The response is a memory object with two more fields. duplicate is true when identical content was already stored. id is then the existing memory, and nothing new is added. replaced lists the ids of the earlier memories that this add replaced, and it is empty when nothing was replaced. Reading and indexing the content bills its model cost to the prepaid credit of the account: about $0.003 for a short note. A long document costs more, because the cost follows the length of the content.

Request

curl -X POST https://api.fryri.com/v1/memories \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Project Atlas uses Python and FastAPI. The launch review is on 14 October.",
    "title": "Project Atlas notes",
    "source_ref": "crm:note:881",
    "end_user_id": "user_42"
  }'

Response

{
  "id": "file_NkolfLrElMmM2fCn",
  "type": "text",
  "title": "Project Atlas notes",
  "status": "processing",
  "status_reason": null,
  "created_at": "2026-09-25T09:02:54.915644Z",
  "source_ref": "crm:note:881",
  "sha256": "886d5886b41216cf0dc8e2234f4ffb24cb5666425200e5e2c5ee33d841b91be4",
  "duplicate": false,
  "replaced": []
}

Duplicates

The same request, sent again, returns the existing memory with duplicate set to true.

Response

{
  "id": "file_NkolfLrElMmM2fCn",
  "type": "text",
  "title": "Project Atlas notes",
  "status": "processing",
  "status_reason": null,
  "created_at": "2026-09-25T09:02:54.915644Z",
  "source_ref": "crm:note:881",
  "sha256": "886d5886b41216cf0dc8e2234f4ffb24cb5666425200e5e2c5ee33d841b91be4",
  "duplicate": true,
  "replaced": []
}

Replace by reference

A memory is one copy of one original. An add with a source_ref that earlier memories carry replaces them. The new content gets a new id, the earlier memories stop appearing in search and answers at once, and replaced lists their ids. An add of unchanged content returns the existing memory with duplicate set to true and keeps it. A failed add leaves the earlier memory in place.

Here src/auth.py was added once before and has changed since. Keep a codebase in sync has a complete script for a whole folder or repository.

Request

curl -X POST https://api.fryri.com/v1/memories \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -F "file=@src/auth.py" \
  -F "source_ref=myrepo/src/auth.py" \
  -F "end_user_id=user_42"

Response

{
  "id": "file_hqjP2q_DlrHZT-4U",
  "type": "document",
  "title": "auth.py",
  "status": "processing",
  "status_reason": null,
  "created_at": "2026-09-25T09:07:09.917301Z",
  "source_ref": "myrepo/src/auth.py",
  "sha256": "785108e6758610a47355924cf936ce293ac1c6e5e6c7cd9b8752c19c78c00e26",
  "duplicate": false,
  "replaced": [
    "file_kR1jHO7CDRwaoCEw"
  ]
}

Upload a file

A multipart/form-data upload takes a file of up to 50 MB. The file type comes from the content type of the part, or from the file name when that is missing or application/octet-stream.

Request

curl -X POST https://api.fryri.com/v1/memories \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -F "file=@atlas-budget.txt" \
  -F "title=Atlas budget" \
  -F "end_user_id=user_42"

Response

{
  "id": "file_khWTQ9FQRD0vNdAx",
  "type": "text",
  "title": "Atlas budget",
  "status": "processing",
  "status_reason": null,
  "created_at": "2026-09-25T09:02:58.286297Z",
  "source_ref": null,
  "sha256": "c6a6c1b533130aa2c02bb580edb9263885ac229f1ebd7016e1a341885a908ee4",
  "duplicate": false,
  "replaced": []
}

Supported files

A file memory holds a document. Fryri reads these files:

An add of a photo, a video or an audio file, judged by its content type or its file extension, fails with 422 unsupported_format and stores nothing.

Add a web page

To remember a web page, fetch it in your own code and add its text, with the address of the page as source_ref. An add of the same address later replaces the earlier copy.

Request

curl -X POST https://api.fryri.com/v1/memories \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Example Domain. This domain is for use in documentation examples.",
    "title": "Example Domain",
    "source_ref": "https://example.com",
    "end_user_id": "user_42"
  }'

GET /v1/memories

GET /v1/memories lists memories, newest first. The list covers every note, document and conversation snapshot in the library, however it arrived. Listing is free.

The response holds memories, an array of memory objects, and next_cursor. Pass next_cursor back as cursor for the next page; it is null on the last page. A cursor from a different list starts again at the first page.

Request

curl "https://api.fryri.com/v1/memories?end_user_id=user_42&limit=2" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

Response

{
  "memories": [
    {
      "id": "file_tjSa4DvE15aMARb4",
      "type": "document",
      "title": "Example Domain.html",
      "status": "ready",
      "status_reason": null,
      "created_at": "2026-09-25T09:03:01.562079Z",
      "source_ref": "https://example.com",
      "sha256": "ff67a9d764d6a2367a187734e697f6a53217db9a21c101d410a113ca871a299d"
    },
    {
      "id": "file_khWTQ9FQRD0vNdAx",
      "type": "text",
      "title": "Atlas budget",
      "status": "ready",
      "status_reason": null,
      "created_at": "2026-09-25T09:02:58.286297Z",
      "source_ref": null,
      "sha256": "c6a6c1b533130aa2c02bb580edb9263885ac229f1ebd7016e1a341885a908ee4"
    }
  ],
  "next_cursor": "eyJwIjp7ImkiOjQ1OSwiayI6..."
}

List one folder or codebase

source_ref_prefix lists the memories you added under one prefix of source_ref, such as the files of one repository.

Request

curl "https://api.fryri.com/v1/memories?end_user_id=user_42&source_ref_prefix=myrepo%2F" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

Response

{
  "memories": [
    {
      "id": "file_hqjP2q_DlrHZT-4U",
      "type": "document",
      "title": "auth.py",
      "status": "processing",
      "status_reason": null,
      "created_at": "2026-09-25T09:07:09.917301Z",
      "source_ref": "myrepo/src/auth.py",
      "sha256": "785108e6758610a47355924cf936ce293ac1c6e5e6c7cd9b8752c19c78c00e26"
    }
  ],
  "next_cursor": null
}

GET /v1/memories/{memory_id}

GET /v1/memories/{memory_id} returns one memory with its status, its text and a link to its original file. Reading is free.

Poll it after an add until status is ready or failed. A short note is usually ready within seconds. A long document can take a few minutes.

A memory of an end user must be read with its end_user_id. Otherwise, the request fails with 404 not_found. A cursor from another memory, or from an earlier version of its text, fails with 422 invalid_cursor.

The response is a memory object with six more fields:

A processed conversation also returns messages on its first page: original role, content and created_at, with 1-based turn, line_start and line_end. Other memories and later pages return messages: null.

The text of a long document arrives in parts. lines counts the same lines as location.line_start in a search result.

Request

curl "https://api.fryri.com/v1/memories/file_NkolfLrElMmM2fCn?end_user_id=user_42" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

Response

{
  "id": "file_NkolfLrElMmM2fCn",
  "type": "text",
  "title": "Project Atlas notes",
  "status": "ready",
  "status_reason": null,
  "created_at": "2026-09-25T09:02:54.915644Z",
  "source_ref": "crm:note:881",
  "sha256": "886d5886b41216cf0dc8e2234f4ffb24cb5666425200e5e2c5ee33d841b91be4",
  "summary": "A brief note about Project Atlas, which uses Python and FastAPI, with a launch review scheduled for 14 October.",
  "text": "Project Atlas uses Python and FastAPI. The launch review is on 14 October.",
  "lines": {
    "start": 1,
    "end": 1,
    "total": 1
  },
  "next_cursor": null,
  "download_url": "https://****.r2.cloudfla..."
}

DELETE /v1/memories/{memory_id}

DELETE /v1/memories/{memory_id} deletes one memory. It stops appearing in search and answers at once, together with anything learned from it. Deleting is free.

A memory of an end user must be deleted with its end_user_id. Otherwise, the request fails with 404 not_found. A second delete of the same memory also fails with 404. To erase everything stored for one end user, call DELETE /v1/end-users/{end_user_id}.

Request

curl -X DELETE "https://api.fryri.com/v1/memories/file_khWTQ9FQRD0vNdAx?end_user_id=user_42" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

Response

{
  "id": "file_khWTQ9FQRD0vNdAx",
  "deleted": true
}

Shared library

The shared library holds the memories every one of your end users reads, such as policies, a menu or a product manual. An add with scope: "shared" puts a memory there. The runs, searches and answers of every end user then include it beside their own memories, marked library: "shared". An end user can open a shared memory it was shown, and nothing an end user does changes the shared library.

Only your own key, without end_user_id, adds to the shared library. GET /v1/memories?scope=shared lists it, and GET and DELETE /v1/memories/{memory_id}?scope=shared read and delete one of its memories. A shared add replaces by source_ref only within the shared library. scope with end_user_id fails with 422 invalid_request.

Request

curl -X POST https://api.fryri.com/v1/memories \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Members may bring one guest per calendar month to any class. Guests sign the waiver at the front desk before the class starts.",
    "title": "Guest policy",
    "source_ref": "policies/guests.md",
    "scope": "shared"
  }'

POST /v1/search

POST /v1/search returns the memories that match a query, best match first. It matches by meaning and by exact words, so a query does not need the wording of the memory. Each result is a memory with its most relevant passage.

Search writes no answer. For an answer with sources, call POST /v1/answer. Each search bills the model cost of reading the query and ranking the matches, reported in cost_usd.

Response fields:

Request

curl -X POST https://api.fryri.com/v1/search \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "When is the Atlas launch review?",
    "end_user_id": "user_42",
    "limit": 3
  }'

Response

{
  "results": [
    {
      "id": "file_NkolfLrElMmM2fCn",
      "type": "text",
      "title": "Project Atlas notes",
      "text": "Project Atlas uses Python and FastAPI. The launch review is on 14 October.",
      "score": 0.526897227015439,
      "score_basis": "cosine",
      "location": null,
      "created_at": "2026-09-25T09:02:54.915644Z",
      "source_ref": "crm:note:881"
    },
    {
      "id": "file_khWTQ9FQRD0vNdAx",
      "type": "text",
      "title": "Atlas budget",
      "text": "Atlas budget\nDesign: 12,000 NZD\nBuild: 30,000 NZD",
      "score": 0.234705295047091,
      "score_basis": "cosine",
      "location": null,
      "created_at": "2026-09-25T09:02:58.286297Z",
      "source_ref": null
    }
  ],
  "next_cursor": null,
  "cost_usd": 0.000001
}

POST /v1/answer

POST /v1/answer answers a question from memories and lists cited evidence and retrieved context separately. One call finds what is relevant, reads it and writes the answer. An answer draws only on the memories of the library, and it never adds or changes a memory.

Answers are unsaved by default. With resumable: true, Fryri retains the completed answer and sources for 48 hours from acceptance, and a completed answer is billed even if you disconnect. The question and incremental transcript are not retained. A repeated POST with the same UUID and question joins or retrieves that answer; a different question returns 409 answer_request_conflict.

GET /v1/answer/{request_id} returns id, status, expires_at, result, error. The statuses are queued, running, completed, failed and interrupted. A completed result has the usual response body below. A POST waiting on another server returns 202 with status and Retry-After: 5. Retrieval does no new inference and needs no additional credit.

A started answer interrupted before its result is saved becomes interrupted after its five-minute lease expires. Fryri does not repeat uncertain model work automatically. A repeated POST returns 409 answer_interrupted; a new UUID explicitly starts a separate answer. DELETE /v1/answer/{request_id} erases the retained answer and returns id, deleted, like the other deletes. After deletion or expiry, retrieval returns 404. Reads and deletes require the original API key and the same end_user_id query parameter, when used on POST. End-user and account deletion also erase retained answers. Deletion does not guarantee cancellation of processing already in progress. A content-free deleted receipt remains until the original expiry: reusing its UUID returns 410 answer_deleted, so a retry cannot silently start and bill a second answer. Use a new UUID for a separate answer.

Response fields:

sources lists numbered citations first, then retrieved context. Read cited to distinguish the two. An answer bills what its model uses, the same as asking in the Fryri app, and reports it in cost_usd.

Request

curl -X POST https://api.fryri.com/v1/answer \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "When is the Atlas launch review, and what does the project use?",
    "end_user_id": "user_42"
  }'

Response

{
  "answer": "The **launch review is on 14 October**, and Project Atlas uses **Python and FastAPI**.\n\nThat's from your \"Project Atlas notes.txt\". Given today's date, that review is about three weeks away. The notes...",
  "sources": [
    {
      "type": "text",
      "id": "file_NkolfLrElMmM2fCn",
      "title": "Project Atlas notes",
      "text": "Project Atlas uses Python and FastAPI. The launch review is on 14 October."
    }
  ],
  "cost_usd": 0.005918
}

Streaming

With stream set to true, the response is text/event-stream. Each event is one data: line that holds a JSON object with a type:

The stream ends with done or error. The answer in done is final, so it replaces the joined delta text. Lines that start with : are heartbeats that keep the connection open. A failure before the first event, such as a missing key, returns the JSON error envelope with its HTTP status.

Request

curl -N -X POST https://api.fryri.com/v1/answer \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "When is the Atlas launch review?",
    "end_user_id": "user_42",
    "stream": true
  }'

Response

data: {"type": "delta", "text": "The Atlas launch review is on **14 October** (per your Project Atlas notes, so 14 October 2026, just under three weeks away)."}

data: {"type": "done", "answer": "The Atlas launch review is on **14 October** (per your Project Atlas notes, so 14 October 2026, just under three weeks away).", "sources": [{"type": "text", "id": "file_NkolfLrElMmM2fCn", "title": "Project Atlas notes", "text": "Project Atlas uses Python and FastAPI. The launch review is on 14 October."}], "cost_usd": 0.005918}

End users

end_user_id scopes a call to one of your own users. Each end user has a private library and their own threads. Calls with the same id only ever reach that end user, and calls without end_user_id use your own account. Every end user also reads your shared library.

The id is any stable id you already use for the user, [1, 256] printable characters. Fryri keeps it exactly as sent, so user_42 and User_42 are two different end users. POST /v1/runs, POST /v1/memories, POST /v1/search and POST /v1/answer create the end user the first time they use its id. Reads and deletes never create one, so a mistyped id reads as an empty library.

The ids belong to your account, so every key of the account reaches the same end users. Spend always lands on your account. The developer console lists your end users and what each one spent.

DELETE /v1/end-users/{end_user_id}

DELETE /v1/end-users/{end_user_id} permanently deletes one end user and everything stored for them: memories, their original files, threads and runs, and everything learned from them. It takes effect at once and cannot be undone. Your own memories and your other end users stay as they are.

Erasing the same id again fails with 404 not_found, and the next add, search or answer with the same id starts a new, empty library. It's recommended to call it from your own account-deletion flow. Deleting is free.

Request

curl -X DELETE "https://api.fryri.com/v1/end-users/user_42" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

Response

{
  "deleted": true,
  "end_user_id": "user_42"
}

Pricing

You pay for what the model and tools use, the same as the Fryri app, from the prepaid credit of the account. Every run, search and answer reports what it charged in cost_usd, and the developer console shows the same amount for each call.

A newly verified account starts with $1 of credit. Starting a run and every memory, search, answer and end-user call need credit, including the free ones. Top-ups, spend caps per key, usage and the request log are in the developer console.

Errors

Every error returns one JSON envelope with its HTTP status. error.code is a stable machine code to branch on, and error.message is prose that may change. error.retryable says whether the same call, sent again unchanged, can succeed. It's recommended to read it instead of inferring from the status. request_id matches the X-Request-ID header.

Some errors carry extra fields: use on a 410, errors (every field problem) on a 422, and key_monthly_budget_usd with key_spend_this_month_usd on key_budget_reached.

An add that the upload pipeline refuses carries that pipeline's own code, HTTP status and retryable, such as storage_quota_exceeded (413) or upload_rate_limit (429, with Retry-After). A 5xx error carries the same envelope, with retryable set to true.

Missing key

curl -X POST https://api.fryri.com/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "x"
  }'

Response 401

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Pass it as 'Authorization: Bearer fryri_sk_...'.",
    "retryable": false
  },
  "request_id": "b4de2b67719241b4b319d6f8fc7cb0d4"
}

Unknown memory id

curl "https://api.fryri.com/v1/memories/file_AAAAAAAAAAAAAAAA" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

Response 404

{
  "error": {
    "code": "not_found",
    "message": "No memory with that id in this library.",
    "retryable": false
  },
  "request_id": "b8bc43a847964c60a8c05612506be894"
}

Unknown field

curl -X POST https://api.fryri.com/v1/memories \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Project Atlas uses Python and FastAPI.",
    "enduser_id": "user_42"
  }'

Response 422

{
  "error": {
    "code": "invalid_request",
    "message": "enduser_id: Extra inputs are not permitted",
    "retryable": false,
    "errors": [
      {
        "type": "extra_forbidden",
        "loc": [
          "body",
          "enduser_id"
        ],
        "msg": "Extra inputs are not permitted",
        "input": "user_42",
        "url": "https://errors.pydantic.dev/2.10/v/extra_forbidden"
      }
    ]
  },
  "request_id": "92fa7a87447044adafc2b36aa8a50203"
}

Retired endpoints

On 25 September 2026 the API moved to the calls on this page. A path from the earlier API fails with 410 endpoint_retired, and error.use names the call to make instead, when one exists.

Retired path

curl -X POST https://api.fryri.com/v1/capture \
  -H "Authorization: Bearer $FRYRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "x"
  }'

Response 410

{
  "error": {
    "code": "endpoint_retired",
    "message": "`POST /v1/capture` was retired on 2026-09-25. Use POST /v1/memories.",
    "retryable": false,
    "use": "POST /v1/memories"
  },
  "request_id": "f13dd44eafa741f4953f93df4e9410a4"
}

Old search method

curl "https://api.fryri.com/v1/search" \
  -H "Authorization: Bearer $FRYRI_API_KEY"

Response 405

{
  "error": {
    "code": "method_not_allowed",
    "message": "`GET /v1/search` is not supported. Use POST.",
    "retryable": false
  },
  "request_id": "913f828f5e7d4c8699222e09845a89be"
}

Removed on 26 September 2026

On 26 September 2026 the API narrowed to text and documents. A request that still uses one of these parts fails as follows: