Get an upload - Cadenya

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const upload = await client.uploads.retrieve('upload_01HXKD2E5NQM3T9AYWCFZ05DNK', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
});

console.log(upload.info);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
upload = client.uploads.retrieve(
    id="upload_01HXKD2E5NQM3T9AYWCFZ05DNK",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(upload.info)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	upload, err := client.Uploads.Get(
		context.TODO(),
		"upload_01HXKD2E5NQM3T9AYWCFZ05DNK",
		cadenya.UploadGetParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", upload.Info)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

upload = cadenya.uploads.retrieve(
  "upload_01HXKD2E5NQM3T9AYWCFZ05DNK",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(upload)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/uploads/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "name": "<string>",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "createdAt": "2023-11-07T05:31:56Z",
    "externalId": "<string>",
    "labels": {},
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "spec": {
    "filename": "<string>",
    "contentType": "<string>",
    "sizeBytes": "<string>"
  },
  "info": {
    "uploadUrl": "<string>",
    "uploadUrlExpiresAt": "2023-11-07T05:31:56Z",
    "createdBy": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "externalId": "<string>",
        "labels": {},
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "email": "<string>",
        "name": "<string>"
      }
    }
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

GET

workspaces

{workspaceId}

uploads

{id}

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const upload = await client.uploads.retrieve('upload_01HXKD2E5NQM3T9AYWCFZ05DNK', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
});

console.log(upload.info);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
upload = client.uploads.retrieve(
    id="upload_01HXKD2E5NQM3T9AYWCFZ05DNK",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(upload.info)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	upload, err := client.Uploads.Get(
		context.TODO(),
		"upload_01HXKD2E5NQM3T9AYWCFZ05DNK",
		cadenya.UploadGetParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", upload.Info)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

upload = cadenya.uploads.retrieve(
  "upload_01HXKD2E5NQM3T9AYWCFZ05DNK",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(upload)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/uploads/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "name": "<string>",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "createdAt": "2023-11-07T05:31:56Z",
    "externalId": "<string>",
    "labels": {},
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "spec": {
    "filename": "<string>",
    "contentType": "<string>",
    "sizeBytes": "<string>"
  },
  "info": {
    "uploadUrl": "<string>",
    "uploadUrlExpiresAt": "2023-11-07T05:31:56Z",
    "createdBy": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "externalId": "<string>",
        "labels": {},
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "email": "<string>",
        "name": "<string>"
      }
    }
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

Read one upload. Its two jobs: tell you whether the bytes have landed, and hand back the signed URL if you need to retry.

const upload = await client.uploads.retrieve(uploadId, { workspaceId });

console.log(upload.info.status);  // 'UPLOAD_STATUS_PENDING'

upload, err := client.Uploads.Get(ctx, uploadID,
	cadenya.UploadGetParams{WorkspaceID: cadenya.String(workspaceID)})

fmt.Println(upload.Info.Status) // UPLOAD_STATUS_PENDING

upload = cadenya.uploads.retrieve(upload_id, workspace_id: workspace_id)

puts upload.info.status # UPLOAD_STATUS_PENDING

curl "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/uploads/${UPLOAD_ID}" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}"

Poll for `COMPLETE` before referencing

If your create and your reference are decoupled, this is the endpoint you poll. A resource rejects an upload until its bytes are in, so wait for UPLOAD_STATUS_COMPLETE:

async function waitForUpload(uploadId: string) {
  for (;;) {
    const { info } = await client.uploads.retrieve(uploadId, { workspaceId });
    if (info.status === 'UPLOAD_STATUS_COMPLETE') return;
    if (info.status === 'UPLOAD_STATUS_EXPIRED') throw new Error('signed URL lapsed; create a new upload');
    await new Promise((r) => setTimeout(r, 1000));
  }
}

The signed URL is not returned here. Capture it at create.

info.uploadUrl is a field on the read, but its value is empty. The signed URL, and uploadUrlExpiresAt, come back only on the create response. Measured: create returns a 1,018-character URL; a later GET returns the same field blank. So there is no re-fetch. Hold the URL from create until the PUT succeeds. Lose it, or let it expire, and your only move is a new upload, not a GET. This endpoint tells you the status of an upload, never how to write to it.

There is no download

The response carries spec (filename, contentType, sizeBytes), info.status, info.createdBy, and the empty info.uploadUrl. It does not carry a download URL. An upload is a way to get bytes into Cadenya and reference them by upload_id; it is not a file store you read back out. The resource that consumed the upload is what serves the content (a memory entry through get_memory, a tool result through its own read path). A missing or wrong ID is a 404.

Create an upload

The three-step flow, and the status lifecycle in full.

Create a memory entry

Where a completed upload_id gets referenced.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId

string

required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

string

required

Example:

"upload_01HXKD2E5NQM3T9AYWCFZ05DNK"

Response

A handle representing a single file upload flow. Clients call CreateUpload to receive a short-lived presigned URL, PUT the file directly to object storage, then reference the upload by id when creating or updating resources that accept binary content.

Uploads are one-shot: once consumed by a creating or updating resource the upload transitions to UPLOAD_STATUS_CONSUMED and cannot be reused. Unused uploads expire and are garbage-collected.

metadata

object

required

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

Show child attributes

spec

object

required

Show child attributes

info

object

required

Show child attributes

​Poll for COMPLETE before referencing

​The signed URL is not returned here. Capture it at create.

​There is no download

​Related

Create an upload

Create a memory entry

Authorizations

Path Parameters

Response

Poll for `COMPLETE` before referencing

The signed URL is not returned here. Capture it at create.

There is no download

Related