Agentuity Documentation

Create durable, resumable data streams with public URLs.

Region

https://streams-usw.agentuity.cloud

Authentication

All requests require a Bearer token. Pass your SDK key in the Authorization header.

Header	Value
`Authorization`	`Bearer YOUR_SDK_KEY`

You can find your SDK key in the Agentuity Console under your project settings.

Create Stream

Create a new stream and receive its stream ID.

POST/stream

https://streams-usw.agentuity.cloud/stream

Request Body

Stream creation payload.

Field	Type	Description
`name`	string	The namespace/group name (1–254 chars)
`metadata`	object	Optional key-value metadata (optional)
`headers`	object	Optional headers map (commonly includes `content-type`) (optional)
`ttl`	number \| null	Stream TTL in seconds (optional)

Response

JSON response containing the new stream ID.

Status	Description
200	Stream created successfully
401	Unauthorized
402	Payment required

Response Fields

Field	Type	Description
`id`	string	Created stream ID

Notes

TTL behavior:

Omitted: Stream expires after the service default period
null or 0: Stream never expires
60–7,776,000: Expires after specified seconds (values outside range are clamped)

Example

curl -X POST 'https://streams-usw.agentuity.cloud/stream' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "agent-logs",
  "metadata": {
    "exportDate": "2024-01-15"
  },
  "headers": {
    "content-type": "application/json"
  }
}'

Get Stream Info

Get stream metadata, size, public URL, and expiration info.

POST/stream/{id}/info

https://streams-usw.agentuity.cloud/stream/{id}/info

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	The stream ID

Request Body

Empty JSON object is required.

Response

JSON object with stream details.

Status	Description
200	Stream info returned
401	Unauthorized
404	Stream not found

Response Fields

Field	Type	Description
`id`	string	Stream ID
`name`	string	Namespace name
`metadata`	object	Stream metadata
`url`	string	Public stream URL
`size_bytes`	number	Current stream size in bytes
`expires_at`	string \| null	ISO 8601 expiration timestamp

Example

curl -X POST 'https://streams-usw.agentuity.cloud/stream/stream_abc123/info' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Download Stream

Download the finalized stream contents as raw binary data.

GET/stream/{id}

https://streams-usw.agentuity.cloud/stream/{id}

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	The stream ID

Response

Raw binary stream data with original content type.

Status	Description
200	Stream data returned
401	Unauthorized
404	Stream not found

Example

curl -X GET 'https://streams-usw.agentuity.cloud/stream/stream_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Streams

List streams with filtering, pagination, and sorting.

POST/stream/list

https://streams-usw.agentuity.cloud/stream/list

Request Body

Optional list filters and pagination controls.

Field	Type	Description
`name`	string	Filter by namespace (optional)
`metadata`	object	Filter by metadata fields (optional)
`limit`	number	Maximum streams to return (optional)
`offset`	number	Offset for pagination (optional)
`sort`	string	Sort by `name`, `created`, `updated`, `size`, `count`, or `lastUsed` (optional)
`direction`	string	Sort direction: `asc` or `desc` (optional)

Response

JSON response with stream list and total count.

Status	Description
200	Stream list returned
401	Unauthorized

Response Fields

Field	Type	Description
`success`	boolean	Whether the request succeeded
`streams`	object[]	Matching streams
`streams[].id`	string	Stream ID
`streams[].name`	string	Namespace name
`streams[].metadata`	object	Stream metadata
`streams[].url`	string	Public stream URL
`streams[].size_bytes`	number	Current stream size in bytes
`streams[].expires_at`	string \| null	ISO 8601 expiration timestamp
`total`	number	Total matches

Example

curl -X POST 'https://streams-usw.agentuity.cloud/stream/list' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "agent-logs",
  "limit": 50
}'

Delete Stream

Delete a stream by ID.

DELETE/stream/{id}

https://streams-usw.agentuity.cloud/stream/{id}

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	The stream ID

Response

Empty response on success.

Status	Description
200	Stream deleted
401	Unauthorized
404	Stream not found

Example

curl -X DELETE 'https://streams-usw.agentuity.cloud/stream/stream_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Append Data

Append a binary chunk (up to 5MB) to an open stream.

POST/stream/{id}/append

https://streams-usw.agentuity.cloud/stream/{id}/append

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	The stream ID

Request Body

Raw binary body. Set Content-Type: application/octet-stream.

Response

Empty response on success.

Status	Description
200	Data appended
401	Unauthorized
413	Chunk too large

Example

curl -X POST 'https://streams-usw.agentuity.cloud/stream/stream_abc123/append' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/octet-stream' \
  -d '<binary data>'

Complete Stream

Finalize stream writing and make it available for reading.

POST/stream/{id}/complete

https://streams-usw.agentuity.cloud/stream/{id}/complete

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	The stream ID

Request Body

Empty body. Optional header: X-Compress: gzip for server-side compression.

Response

Empty response on success.

Status	Description
200	Stream completed
401	Unauthorized

Example

curl -X POST 'https://streams-usw.agentuity.cloud/stream/stream_abc123/complete' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'