# Files

> Text kept under a path, handed back exactly as it was written and learned from like a note.

Text kept under a path, handed back exactly as it was written and learned from like a note. This page is generated from the API's own spec, so it says exactly what the API does.

## Write a file: kept exactly as sent, and learned from

`PUT /v1/files`

For an agent that keeps its own notes as files, such as Claude's memory tool. The text is kept exactly as
sent and handed back the same by GET /v1/files; what it says is learned as a note titled by its path, so
context and ask recall it too. Written again, the file is replaced and only what changed is learned. An empty
file is kept, with nothing learned from it.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `X-Geniffy-Space` | header | string | One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters) |

**Body** (application/json)

| Field | Type | | Description |
| --- | --- | --- | --- |
| `path` | string | required | Where the file is kept, such as /memories/notes.md: it starts with "/", is up to 255 characters and doesn't end with "/", with no empty, "." or ".." part, backslash or control character |
| `text` | string | required | Its whole text, kept exactly as sent: no space or line ending is changed. An empty file is kept too, with nothing learned from it (up to 2,000,000 characters) |
| `labels` | object | optional | Up to 20 of your own name/value pairs, such as {"channel": "claude-memory"}, to filter what you recall by. Written again, they replace the old ones; left out, they are kept; {} clears them |
| `space` | string | optional | One of your own users. Leave it out for your own memory; a blank one is refused. (up to 128 characters) |

**Returns** `200`

| Field | Type | | Description |
| --- | --- | --- | --- |
| `path` | string | required |  |
| `size` | integer | required | How many characters its text holds |
| `updated_at` | string | required | When it was last written |
| `created` | boolean | required | true when there was no file at this path before |
| `source` | object | required | The source it is learned from: a note titled by its path |

## Read a file, or list the files under a prefix

`GET /v1/files`

With path, that file's text, exactly as it was written. With prefix instead, the files whose path starts
with it, in path order: each one's path, size and when it was last written.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `path` | query | string | One file, by its path, such as /memories/notes.md |
| `prefix` | query | string | Every file whose path starts with this: /memories/ for those beneath that directory, / for all of them |
| `limit` | query | integer |  (at least 1; at most 200; default `100`) |
| `cursor` | query | integer |  (at least 0; default `0`) |
| `space` | query | string | One of your own users. Leave it out for your own memory; a blank one is refused. (up to 128 characters) |
| `X-Geniffy-Space` | header | string | One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters) |

**Returns** `200`, one file

| Field | Type | | Description |
| --- | --- | --- | --- |
| `path` | string | required |  |
| `text` | string | required | Exactly as it was written |
| `size` | integer | required | How many characters it holds |
| `updated_at` | string | required | When it was last written |

**Returns** `200`, files under a prefix

| Field | Type | | Description |
| --- | --- | --- | --- |
| `files` | array of FileRow | required | In path order, character by character |
| `total` | integer | required |  |
| `next` | integer | optional |  |

## Delete a file, or the files under a prefix

`DELETE /v1/files`

The file, its text and every memory learned only from it. Or, with prefix instead, every file whose path
starts with it, each the same way: up to 100 a call, and `more` says to call again.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `path` | query | string | One file, by its path, such as /memories/notes.md |
| `prefix` | query | string | Every file whose path starts with this: /memories/ for those beneath that directory, / for all of them |
| `space` | query | string | One of your own users. Leave it out for your own memory; a blank one is refused. (up to 128 characters) |
| `X-Geniffy-Space` | header | string | One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters) |

**Returns** `200`, by path

| Field | Type | | Description |
| --- | --- | --- | --- |
| `deleted` | integer | required | 1: the file |
| `path` | string | required |  |

**Returns** `200`, by prefix

| Field | Type | | Description |
| --- | --- | --- | --- |
| `deleted` | integer | required | How many files this call deleted, up to 100 |
| `more` | boolean | required | Other files start with that prefix: call again |

## Move a file, or every file beneath a directory

`POST /v1/files/move`

The file at from goes to to, keeping its text and what it taught: nothing is learned again. With no file at
from, every file beneath from/ moves to the same place beneath to/. When a file is already at any path they
would take, nothing moves.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `X-Geniffy-Space` | header | string | One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters) |

**Body** (application/json)

| Field | Type | | Description |
| --- | --- | --- | --- |
| `from` | string | required | The file to move or, when no file is there, the directory whose files move |
| `to` | string | required | Where it goes, or the directory they go beneath |
| `space` | string | optional | One of your own users. Leave it out for your own memory; a blank one is refused. (up to 128 characters) |

**Returns** `200`

| Field | Type | | Description |
| --- | --- | --- | --- |
| `moved` | integer | required | How many files moved |

Source: https://docs.geniffy.com/api/files