Open a folder

Open a folder of attachments

curl --request POST \
  --url https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/attachments/folders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "end_user": "u_dana_ortiz",
  "name": "supplier-contracts",
  "files": [
    {
      "path": "supplier-contracts/contract-2026.pdf",
      "size_bytes": 482113
    },
    {
      "path": "supplier-contracts/contract-2025.pdf",
      "size_bytes": 391208
    }
  ]
}
'

import requests

url = "https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/attachments/folders"

payload = {
    "end_user": "u_dana_ortiz",
    "name": "supplier-contracts",
    "files": [
        {
            "path": "supplier-contracts/contract-2026.pdf",
            "size_bytes": 482113
        },
        {
            "path": "supplier-contracts/contract-2025.pdf",
            "size_bytes": 391208
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    end_user: 'u_dana_ortiz',
    name: 'supplier-contracts',
    files: [
      {path: 'supplier-contracts/contract-2026.pdf', size_bytes: 482113},
      {path: 'supplier-contracts/contract-2025.pdf', size_bytes: 391208}
    ]
  })
};

fetch('https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/attachments/folders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "container": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "filename": "<string>",
    "media_type": "<string>",
    "size_bytes": 123,
    "status": "storing",
    "delivery": "file",
    "created_at": "2023-11-07T05:31:56Z",
    "notice": "<string>",
    "error": "<string>",
    "container_kind": "zip",
    "parent_attachment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "reused": true,
  "members": [
    {
      "attachment": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "media_type": "<string>",
        "size_bytes": 123,
        "status": "storing",
        "delivery": "file",
        "created_at": "2023-11-07T05:31:56Z",
        "notice": "<string>",
        "error": "<string>",
        "container_kind": "zip",
        "parent_attachment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "expires_at": "2023-11-07T05:31:56Z"
      },
      "upload_url": "<string>",
      "upload_url_expires_at": "2023-11-07T05:31:56Z",
      "source_path": "<string>"
    }
  ],
  "skipped": [
    {
      "path": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "container": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "filename": "<string>",
    "media_type": "<string>",
    "size_bytes": 123,
    "status": "storing",
    "delivery": "file",
    "created_at": "2023-11-07T05:31:56Z",
    "notice": "<string>",
    "error": "<string>",
    "container_kind": "zip",
    "parent_attachment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "reused": true,
  "members": [
    {
      "attachment": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "media_type": "<string>",
        "size_bytes": 123,
        "status": "storing",
        "delivery": "file",
        "created_at": "2023-11-07T05:31:56Z",
        "notice": "<string>",
        "error": "<string>",
        "container_kind": "zip",
        "parent_attachment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "expires_at": "2023-11-07T05:31:56Z"
      },
      "upload_url": "<string>",
      "upload_url_expires_at": "2023-11-07T05:31:56Z",
      "source_path": "<string>"
    }
  ],
  "skipped": [
    {
      "path": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "unauthorized",
  "message": "Missing or invalid API key"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "rate_limited",
  "message": "Rate limit exceeded"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "attachments_unavailable",
  "message": "File attachments are not available in this environment."
}

{
  "code": "request_timeout",
  "message": "Request timed out"
}

POST

api

conversation-instances

{instance_slug}

conversations

{conversation_id}

attachments

folders

Open a folder of attachments

curl --request POST \
  --url https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/attachments/folders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "end_user": "u_dana_ortiz",
  "name": "supplier-contracts",
  "files": [
    {
      "path": "supplier-contracts/contract-2026.pdf",
      "size_bytes": 482113
    },
    {
      "path": "supplier-contracts/contract-2025.pdf",
      "size_bytes": 391208
    }
  ]
}
'

import requests

url = "https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/attachments/folders"

payload = {
    "end_user": "u_dana_ortiz",
    "name": "supplier-contracts",
    "files": [
        {
            "path": "supplier-contracts/contract-2026.pdf",
            "size_bytes": 482113
        },
        {
            "path": "supplier-contracts/contract-2025.pdf",
            "size_bytes": 391208
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    end_user: 'u_dana_ortiz',
    name: 'supplier-contracts',
    files: [
      {path: 'supplier-contracts/contract-2026.pdf', size_bytes: 482113},
      {path: 'supplier-contracts/contract-2025.pdf', size_bytes: 391208}
    ]
  })
};

fetch('https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/attachments/folders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "container": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "filename": "<string>",
    "media_type": "<string>",
    "size_bytes": 123,
    "status": "storing",
    "delivery": "file",
    "created_at": "2023-11-07T05:31:56Z",
    "notice": "<string>",
    "error": "<string>",
    "container_kind": "zip",
    "parent_attachment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "reused": true,
  "members": [
    {
      "attachment": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "media_type": "<string>",
        "size_bytes": 123,
        "status": "storing",
        "delivery": "file",
        "created_at": "2023-11-07T05:31:56Z",
        "notice": "<string>",
        "error": "<string>",
        "container_kind": "zip",
        "parent_attachment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "expires_at": "2023-11-07T05:31:56Z"
      },
      "upload_url": "<string>",
      "upload_url_expires_at": "2023-11-07T05:31:56Z",
      "source_path": "<string>"
    }
  ],
  "skipped": [
    {
      "path": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "container": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "filename": "<string>",
    "media_type": "<string>",
    "size_bytes": 123,
    "status": "storing",
    "delivery": "file",
    "created_at": "2023-11-07T05:31:56Z",
    "notice": "<string>",
    "error": "<string>",
    "container_kind": "zip",
    "parent_attachment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "reused": true,
  "members": [
    {
      "attachment": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "media_type": "<string>",
        "size_bytes": 123,
        "status": "storing",
        "delivery": "file",
        "created_at": "2023-11-07T05:31:56Z",
        "notice": "<string>",
        "error": "<string>",
        "container_kind": "zip",
        "parent_attachment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "expires_at": "2023-11-07T05:31:56Z"
      },
      "upload_url": "<string>",
      "upload_url_expires_at": "2023-11-07T05:31:56Z",
      "source_path": "<string>"
    }
  ],
  "skipped": [
    {
      "path": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "unauthorized",
  "message": "Missing or invalid API key"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "rate_limited",
  "message": "Rate limit exceeded"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "attachments_unavailable",
  "message": "File attachments are not available in this environment."
}

{
  "code": "request_timeout",
  "message": "Request timed out"
}

Behavior

Upload each member’s bytes to its upload_url, then finalize each member. The folder becomes ready when every member is finalized. A folder already open and ready with the same roster (member paths and declared sizes; contents are not compared) answers 200 with reused: true and nothing to upload; otherwise a new folder answers 201. Files the instance will not read are listed in skipped. See Attachments.

Authorizations

Authorization

string

header

required

Send the key as Authorization: Bearer <key>. Two kinds of key exist.

Organization keys are issued in the portal (Settings, then API keys), each bound to one environment, shaped nx_<environment slug>_<64 hex>. They carry no capabilities and pass every capability check, with one exception: routes under /api/v1/records, /api/v1/engines/{id}/opportunities, /api/v1/graph and /api/v1/catalog/documents accept an organization key only when its environment is live, and refuse any other with 403 scoped_key_required. Revocation takes effect within 60 seconds.

Scoped keys are issued by Nexio on request, shaped nxsk_v1_<24 hex key id>_<43 character secret>. Each is bound to one org, one environment, a set of engines and a set of capabilities. A malformed, unknown or revoked nxsk_ key fails with 401 and is never retried as an organization key. Revocation takes effect on the next request. A scoped key without a route's capability gets 403 insufficient_capability; a scoped key not bound to the engine gets 403 engine_binding_forbidden.

Key-grantable capabilities: engines:read, runs:write, runs:read, runs:defensibility:read, runs:test, catalog:read, catalog:documents:read, webhooks:manage, conversations:use, conversations:export, records:read, records:opportunities:run, actions:write, actions:read, graph:read, records:analyze.

Routes that accept organization keys only (every scoped key gets 403 insufficient_capability): environment management, engine create, update, configuration and publish, and conversation instance authoring. Each operation description names the capability a scoped key needs.

Path Parameters

instance_slug

string

required

Conversation instance identifier slug (e.g. platform-assistant).

conversation_id

string<uuid>

required

Body

application/json

end_user

string

required

The asserted end-user identity the conversation must belong to.

name

string

required

Folder name.

files

object[]

required

Maximum array length: 25

Hide child attributes

files.path

string

required

The file's path inside the folder, as your application holds it. Echoed back as source_path.

files.size_bytes

integer<int64>

required

Declared size in bytes. Zero or less is skipped as empty; over the per-file limit is skipped as too large.

Response

The same folder was already open and ready; it is returned with reused true and no members to upload.

An opened folder container with one reservation per readable file.

container

object

required

One file attached to a conversation. There is no text field: the platform does not parse the document, it hands the bytes to the model.

Hide child attributes

container.id

string<uuid>

required

container.filename

string

required

container.media_type

string

required

container.size_bytes

integer<int64>

required

container.status

enum<string>

required

ready can ride a turn. A multipart upload answers ready. A reserved upload is storing until finalize; a folder container is unwrapping until every member is finalized. A finalize that finds no bytes leaves the record storing. A finalize that refuses the file for any other reason marks it rejected and removes it at once, so it no longer lists or reads. failed is reserved and not currently set. Only ready records can ride a turn or be served.

Available options:

storing,

unwrapping,

ready,

rejected,

failed

container.delivery

enum<string>

required

How the file reaches the model. file and image are provider inputs. unwrap is a container, which never reaches the model itself; a turn naming it carries the files inside it.

A folder container also has delivery unwrap.

Available options:

file,

image,

unwrap

container.created_at

string<date-time>

required

container.notice

string

How this format is read, when there is a limit worth knowing. On a zip or email container it says how many files were read and what was left out; on a folder container it says how many files the folder holds. A spreadsheet is read to the first 1,000 rows per sheet; text is read out of Office files while images and charts inside them are not. Absent when the file is read whole. Show it: an answer drawn from part of a schedule is not an answer about the schedule.

container.error

string

Why the record was rejected or failed. Absent otherwise.

container.container_kind

enum<string>

What a container is. zip and eml are opened by the platform; folder is opened by the client and its files uploaded one by one. Set on a folder, and on a zip or email stored through finalize. Absent on a zip or email stored by a multipart upload, on a plain file, and on a file inside a container.

Available options:

zip,

eml,

folder

container.parent_attachment_id

string<uuid>

The container this file was found inside, when it was.

container.expires_at

string<date-time>

When access to the attachment ends. From this moment it is left out of lists, answers 404 when read or downloaded, and cannot be named on a turn. A later retention sweep deletes the record and removes the bytes. Absent when the attachment follows its conversation's own retention.

reused

boolean

required

True when a folder with the same roster (member paths and declared sizes; contents are not compared) was already open and ready and is handed back; members is empty and nothing needs uploading.

members

object[]

required

Hide child attributes

members.attachment

object

required

One file attached to a conversation. There is no text field: the platform does not parse the document, it hands the bytes to the model.

Hide child attributes

members.attachment.id

string<uuid>

required

members.attachment.filename

string

required

members.attachment.media_type

string

required

members.attachment.size_bytes

integer<int64>

required

members.attachment.status

enum<string>

required

Available options:

storing,

unwrapping,

ready,

rejected,

failed

members.attachment.delivery

enum<string>

required

How the file reaches the model. file and image are provider inputs. unwrap is a container, which never reaches the model itself; a turn naming it carries the files inside it.

A folder container also has delivery unwrap.

Available options:

file,

image,

unwrap

members.attachment.created_at

string<date-time>

required

members.attachment.notice

string

members.attachment.error

string

Why the record was rejected or failed. Absent otherwise.

members.attachment.container_kind

enum<string>

Available options:

zip,

eml,

folder

members.attachment.parent_attachment_id

string<uuid>

The container this file was found inside, when it was.

members.attachment.expires_at

string<date-time>

members.upload_url

string<uri>

required

Presigned PUT URL for this one file. Send the raw bytes with no Authorization header. It cannot read and cannot reach any other file.

members.upload_url_expires_at

string<date-time>

required

When upload_url stops working, 15 minutes after it was issued.

members.source_path

string

For a folder member, the path your request sent for it, echoed verbatim. Absent on a standalone reservation.

skipped

object[]

required

Files the instance will not read. Always present; empty when nothing was skipped.

Hide child attributes

skipped.path

string

required

The path as your request sent it.

skipped.reason

string

required

Why it was skipped, in words a person can act on.

Last modified on September 25, 2026

Overview

Engines

Environments

Conversations

Webhooks

Events

Records

Graph

Platform

Open a folder

Behavior

Authorizations

Path Parameters

Body

Response

​Behavior

Authorizations

Path Parameters

Body

Response

Behavior