# files/v1 (/docs/a2a/files/v1)



URI: `https://docs.nylorun.com/a2a/files/v1`

```json
{
  "artifactUpdate": {
    "taskId": "t1.…",
    "contextId": "ticket-4821",
    "artifact": {
      "artifactId": "af_01m663pz…:deepwiki-portal.zip",
      "name": "deepwiki-portal.zip",
      "parts": [
        {
          "url": "https://runtime.example.com/v1/a2a/files/af_01m663pz…/versions/2",
          "mediaType": "application/zip",
          "filename": "deepwiki-portal.zip"
        }
      ],
      "extensions": ["https://docs.nylorun.com/a2a/files/v1"],
      "metadata": {
        "https://docs.nylorun.com/a2a/files/v1": {
          "kind": "file",
          "path": "deepwiki-portal.zip",
          "version": 2,
          "size": 2394141,
          "sha256": "a561e811…"
        }
      }
    },
    "append": false,
    "lastChunk": true
  }
}
```

Each [artifact](/docs/run/files) the turn writes, or adds a version to,
becomes an A2A artifact with this extension: by push as an `artifactUpdate`,
and in the task's `artifacts` from `GetTask`, which lists the latest version of
each. Files the caller sent in are not listed. The turn's answer is a separate
artifact, `output`, without this extension.

The artifact's part is a `url`:
[`GET /v1/a2a/files/{artifactId}/versions/{version}`](/reference/runtime/sessions/a2a/download-a-file-an-a2a-task-wrote)
on the Runtime's public URL. It serves the version's bytes, with `Range`, or a
folder's version as a zip. Only the subject whose session wrote it may read it:
fetch it with the same key, `Nylorun-Subject`, and `Nylorun-Scopes` you called
the Agent with. Another subject gets `404`.

| Field       | Type                 | Meaning                                                                                    |
| ----------- | -------------------- | ------------------------------------------------------------------------------------------ |
| `kind`      | `file` or `folder`   | A file, or a folder served as its zip.                                                     |
| `path`      | string               | The artifact's name, such as the path the agent saved it under. The same across versions.  |
| `version`   | number               | The version. A later write to the same artifact is a higher version.                       |
| `size`      | number               | Bytes of the version.                                                                      |
| `sha256`    | string               | The SHA-256 of the content, in hex. Two versions with the same hash have the same content. |
| `fileCount` | number, folders only | The files in the folder's version.                                                         |

Index files by `path` and `version`. The same artifact can arrive more than
once, by push and by `GetTask`; the same `path`, `version`, and `sha256` is the
same file.

## Files into a task [#files-into-a-task]

A message can carry files as `raw` parts or as `url` parts. The Runtime fetches
a `url` part itself, within the Runtime limit `inlineFileBytes` (20 MiB by
default) and 60 seconds, and stores it like a `raw` part. It fetches only from
hosts a push may reach: a private, loopback, or link-local address is refused
unless the operator allows it (see [Allowed hosts](/docs/a2a/push#allowed-hosts)).
A URL that is refused or does not answer `2xx` refuses the message. See
[Files in AG-UI and A2A messages](/docs/run/files#files-in-ag-ui-and-a2a-messages).