# Resources and conventions

> The APIs, the objects they return, and the conventions every response follows.

## Memory APIs

These APIs use an API key (`Authorization: AugentaKey <key>`).

| API                                                       | Purpose                                                                                                               |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [Consolidate API](https://augenta.pages.dev/docs/consolidate.md) | Extract claims and group them into engrams one-shot, or add them to a Workspace where engrams form in the background. |
| [Experiences API](https://augenta.pages.dev/docs/experiences.md) | Add conversations and documents to a Workspace in the background, and check their processing.                         |
| [Recall API](https://augenta.pages.dev/docs/recall.md)           | Retrieve the memory relevant to a question, for your model to read.                                                   |
| [Engrams API](https://augenta.pages.dev/docs/engrams.md)         | Read a Workspace's engrams and the claims each one holds.                                                             |
| [Events API](https://augenta.pages.dev/docs/events.md)           | Follow engrams being created, split, merged and retired.                                                              |

Claims and engrams are formed by processing your source material. There are no endpoints to
create, edit or delete an individual claim or engram. One-shot results are not stored and have no
URL to read them again.

## Administration APIs

Administration uses a signed-in person's credentials, which the console uses on your behalf. An
API key cannot administer its organization.

| API                                                           | Purpose                                                          |
| ------------------------------------------------------------- | ---------------------------------------------------------------- |
| [Organizations API](https://augenta.pages.dev/docs/organizations.md) | Read organizations and their members.                            |
| [Workspaces API](https://augenta.pages.dev/docs/workspaces.md)       | Create and manage Workspaces, their members and their lifecycle. |
| [API Keys](https://augenta.pages.dev/docs/api-keys.md)               | Create, inspect and revoke API keys.                             |

## Objects

Every returned object has an `id` and an `object` field naming its type: `engram`, `claim`,
`experience`, `event`, `workspace`, `organization` or `api_key`. Each type has an object page in
the [API reference](https://augenta.pages.dev/docs/api-reference.md) listing its operations and every attribute.

Consolidate and Recall return results rather than stored objects. Recall's `content` blocks are
text prepared for a model, not engram or claim objects.

## Lists

Every paginated list has the same shape, whether it is a response on its own or a field such as
an engram's `claims`:

```json
{ "object": "list", "data": [], "nextPageUrl": null }
```

`data` holds this page. When `nextPageUrl` is not `null`, request it with `GET`, unchanged, for
the next page. A page can be short, or even empty, and still have a next page. See
[Pagination](https://augenta.pages.dev/docs/pagination.md).

## Including related data

Some reads accept `include` to load a related collection in the same response: `include=claims`
loads the first page of each engram's claims in a list, and `include=members` loads the first page
of members on an organization or Workspace. An included collection is a list like any other:
follow its `nextPageUrl` for the rest.

A field that was not loaded is left out of the response. A field that is `null` was loaded and has
no value.
