Skip to content
cadenya
Get started
API Reference
Uploads

Create an upload

client.Uploads.New(ctx, body) (*Upload, error)
POST/v1/uploads

Issues a short-lived presigned URL for direct upload to object storage. The returned id is used to reference the upload from resources that accept binary content.

ParametersExpand Collapse
body UploadNewParams
Metadata param.Field[CreateResourceMetadata]

CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

Spec param.Field[UploadSpec]
ReturnsExpand Collapse
type Upload struct{…}

Upload is a workspace-scoped 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 by the runtime.

CreatedBy Profileoptional

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

ID string

Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string
ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

ProfileSpec contains the profile-specific fields

Type ProfileSpecType

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum
One of the following:
const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"
const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"
const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"
Email stringoptional

Email address of the user (required, unique per account)

Name stringoptional

Display name for the user (e.g., "Bobby Tables")

Status UploadInfoStatusoptional

Lifecycle state. Transitions PENDING → COMPLETE (storage confirms the object exists) → CONSUMED (a resource referenced this upload), or → EXPIRED (URL elapsed without a PUT).

formatenum
One of the following:
const UploadInfoStatusUploadStatusUnspecified UploadInfoStatus = "UPLOAD_STATUS_UNSPECIFIED"
const UploadInfoStatusUploadStatusPending UploadInfoStatus = "UPLOAD_STATUS_PENDING"
const UploadInfoStatusUploadStatusComplete UploadInfoStatus = "UPLOAD_STATUS_COMPLETE"
const UploadInfoStatusUploadStatusConsumed UploadInfoStatus = "UPLOAD_STATUS_CONSUMED"
const UploadInfoStatusUploadStatusExpired UploadInfoStatus = "UPLOAD_STATUS_EXPIRED"
UploadURL stringoptional

Presigned PUT URL. Short-lived. The client must PUT with the exact Content-Type declared in the spec, and the body length must match size_bytes.

UploadURLExpiresAt Timeoptional

Absolute time at which upload_url stops working.

formatdate-time

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

ID string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

CreatedAt Time

Timestamp when this resource was created

formatdate-time
Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string

ID of the actor (user or service account) that created this resource

WorkspaceID string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

ContentType string

MIME type the client will send. Baked into the presigned URL's signature — the PUT must match exactly or object storage will reject it.

Filename string

Client-supplied filename. Used for audit and display only; does not control the object's storage path.

SizeBytes string

Expected size of the upload in bytes. Baked into the presigned URL as a Content-Length constraint.

Create an upload

package main

import (
  "context"
  "fmt"

  "github.com/cadenya/cadenya-go"
  "github.com/cadenya/cadenya-go/option"
  "github.com/cadenya/cadenya-go/shared"
)

func main() {
  client := cadenya.NewClient(
    option.WithAPIKey("My API Key"),
  )
  upload, err := client.Uploads.New(context.TODO(), cadenya.UploadNewParams{
    Metadata: cadenya.F(shared.CreateResourceMetadataParam{
      Name: cadenya.F("name"),
    }),
    Spec: cadenya.F(cadenya.UploadSpecParam{
      ContentType: cadenya.F("contentType"),
      Filename: cadenya.F("filename"),
      SizeBytes: cadenya.F("sizeBytes"),
    }),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", upload.Info)
}

{
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_USER",
        "email": "email",
        "name": "name"
      }
    },
    "status": "UPLOAD_STATUS_UNSPECIFIED",
    "uploadUrl": "uploadUrl",
    "uploadUrlExpiresAt": "2019-12-27T18:11:19.117Z"
  },
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "contentType": "contentType",
    "filename": "filename",
    "sizeBytes": "sizeBytes"
  }
}
Returns Examples
{
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_USER",
        "email": "email",
        "name": "name"
      }
    },
    "status": "UPLOAD_STATUS_UNSPECIFIED",
    "uploadUrl": "uploadUrl",
    "uploadUrlExpiresAt": "2019-12-27T18:11:19.117Z"
  },
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "contentType": "contentType",
    "filename": "filename",
    "sizeBytes": "sizeBytes"
  }
}