> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Spaces

Without a space, every call happens in a hidden workspace. Files there are temporary and unindexed. They die with the run that used them. A **space** is the opposite. Files belong to the space and outlive their runs. They are indexed, so you can [search](#search-a-space) them.

Use a space when several calls belong together: one customer onboarding, one case file, one batch you want to search later.

## Create a space

```bash
curl -X POST https://api.cloudraker.com/v1/spaces \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme onboarding", "ttl": 604800 }'
```

```json
{
  "object": "space",
  "id": "2f6d1c48-9b7a-4b2c-9a3e-1d5f8c0b7e21",
  "name": "Acme onboarding",
  "createdAt": "2026-08-15T09:12:00.114Z",
  "expiresAt": "2026-08-22T09:12:00.114Z"
}
```

| Field  | What it is                                                                                           |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `name` | Optional, ≤ 120 characters. Defaults to `API space`.                                                 |
| `ttl`  | Seconds until the space expires, from `300` to `7776000` (90 days). Defaults to `604800` (one week). |

## Lifetime

`expiresAt` is the deadline. Extend it at any time. The new `ttl` counts from now:

```bash
curl -X PATCH https://api.cloudraker.com/v1/spaces/$SPACE_ID \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ttl": 2592000 }'
```

`DELETE /v1/spaces/{spaceId}` closes the space immediately and deletes its files. It is idempotent. Call it again to finish a purge that was too large for one pass.

### Expiry is lazy

No background process sweeps expired spaces today. The **first call that addresses an expired space** closes it. The space is archived, its files are deleted in the background, and the call answers `404`.

Design for three consequences:

* A space past `expiresAt` is already gone as far as this API is concerned, even before anything touched it.
* The [`space.expired` webhook](/developers/webhooks#event-types) fires at that moment — once per space, not at the deadline. Advance warnings arrive with the sweeper later.
* An explicit `DELETE` does **not** emit `space.expired`. Deleting your own space is not an expiry.

## The namespaced mirror

Every `/v1` route that works on the hidden workspace works inside a space, under `/v1/spaces/{spaceId}/…`:

| Inside a space                                                                                            | What it does                                                                            |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `POST /v1/spaces/{spaceId}/extract` (also `extract/batch`, `parse`, `redact`, `fill`, `sign`, `pipeline`) | The [capabilities](/capabilities/extract), over the space's files.                      |
| `POST` / `GET` / `DELETE /v1/spaces/{spaceId}/files…`                                                     | Register, list, read and delete files — plus every [file tool](/developers/file-tools). |
| `GET /v1/spaces/{spaceId}/runs` and `/runs/{id}`                                                          | The [runs](/developers/runs) that happened in this space.                               |
| `GET /v1/spaces/{spaceId}/search?q=…`                                                                     | Search the space's indexed files.                                                       |
| `POST /v1/spaces/{spaceId}/agents`, `GET …/agents/{runId}`                                                | [Agent runs](/developers/agent-runs) scoped to the space.                               |

Bodies and responses are identical to the unscoped routes. Only the path changes.

The mirror works on **any** live space of your organization, including spaces people created in the app. Lifecycle does not. `PATCH` and `DELETE` accept only a space created with `POST /v1/spaces`, so this API can never change or delete a space a person made.

## Search a space

```bash
curl "https://api.cloudraker.com/v1/spaces/$SPACE_ID/search?q=termination%20clause&limit=10" \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY"
```

Only files in a space are indexed. Files in the hidden workspace are not, so there is nothing to search there.

## List spaces

```bash
curl "https://api.cloudraker.com/v1/spaces?limit=50" \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY"
```

## Next steps

#### [File tools](/developers/file-tools)

Convert, split, join and redline the files in a space.

#### [Files](/developers/files)

Registering documents and presigned uploads.

#### [Webhooks](/developers/webhooks)

Including `space.expired`.

#### [Runs](/developers/runs)

Reading results and keeping them.