---
search:
  tags:
    - Sessions
    - POST
seo:
  description: >-
    Include files in a session that already exists, each with whatever…
    Reference for the POST /v1/sessions/id/{session_id}/files endpoint in the
    Roboto REST API.
sidebar:
  label: Add files
  badge: POST
title: Add files
type: openapi-operation
---
Include files in a session that already exists, each with whatever topic data it declares.

Answers 200 once the request has been processed, even when the platform included only some of the files:
the response carries one element per declared file, in request order, holding either that file's membership in
the shape ``GET /v1/sessions/id/<session_id>/files`` reports it or the error that refused the entry.
The request runs in one transaction, and every entry's refusal is settled before anything is written,
so a refused entry leaves the others included; a failure the platform did not anticipate, such as the request's
deadline, includes none of them. A malformed request answers 400, and a file an entry declares, or a file a
listed representation names, that is not an ``Available`` file of the session's org answers 404;
both are settled before the first entry is written, so the session gains nothing.
A session deleted after the request loaded it answers 404, and none of the entries is written.

A client on an API version before 2026-10-05 sends the earlier request shape and receives the
session's record. Its request stands or falls whole: when the platform refuses one file it answers
with that refusal and includes none of the files, and a file named twice is included over its last
entry.

Every ``anchor_ns`` in the body is a time after the Unix epoch: an integer of nanoseconds since the
epoch, or any time ``roboto.time.to_epoch_nanoseconds`` reads, so a float or numeric string is seconds
and an ISO 8601 string is that instant.

Declaring topics on a file or anchoring it writes to that file and so requires edit access to it.
Naming a file in a listed representation writes nothing to that file and takes the access that declaring topics
on it does, because a read of the topic opens that file. Stating ``is_default_for_reads`` on a timeline source,
true or false, additionally requires topic edit access in the org: which source a schema's reads fall back to
is a property of the org's topics, not of any one file. Each denial answers 401 before any entry is prepared.

### Access control
 - Restricted tokens need the API scope `api.everything_else`

`POST /v1/sessions/id/{session_id}/files`