Files API — eyeball docs

Stage attachment bytes and list or retrieve project-scoped file metadata.

`FilesClient`

Project-scoped staging for file content referenced by later tool calls.

`get`

Retrieves metadata for a staged file without returning its bytes.

get(fileId: `file_${string}`): Promise<StagedFileMetadata>

Parameter	Type	Required	Description
`fileId`	`file_${string}`	Yes	Project-scoped staged file identifier.

Returns: Promise<StagedFileMetadata>

Throws

EyeballError when the file is unavailable or the executor request fails.

`list`

Lists unexpired project staged-file metadata in newest-first order.

list(options?: ListFilesOptions): Promise<StagedFilePage>

Parameter	Type	Required	Description
`options`	`ListFilesOptions`	No	Opaque continuation cursor and a page size from 1 through 100; the executor defaults to 100.

Returns: Promise<StagedFilePage>

Throws

EyeballError when options are invalid, the key lacks project authority, or the executor request fails.

Example

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const first = await eyeball.files.list({ limit: 50 });
for (const file of first.files) console.log(file.name, file.expiresAt);
if (first.nextCursor !== undefined) {
  const next = await eyeball.files.list({
    cursor: first.nextCursor,
    limit: 50,
  });
  console.log(next.files.length);
}

`upload`

Stages UTF-8 text or exact bytes and returns the attachment reference accepted by tools.

upload(options: UploadFileOptions): Promise<StagedFileReference>

Parameter	Type	Required	Description
`options`	`UploadFileOptions`	Yes	File name, optional media type, and content to stage.

Returns: Promise<StagedFileReference>

Throws

EyeballError when the upload is rejected or the executor cannot be reached.

Example

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const invoiceBytes = new Uint8Array();

const attachment = await eyeball.files.upload({
  name: "invoice.pdf",
  mimeType: "application/pdf",
  content: invoiceBytes,
});

Types

`ListFilesOptions`

Cursor and page-size controls for project staged-file listing.

export interface ListFilesOptions {
  cursor?: string;
  limit?: number;
}

Property	Type	Required	Readonly	Description
`cursor`	`string`	No	No	—
`limit`	`number`	No	No	—

`UploadFileOptions`

Name, media type, and exact content staged by files.upload.

export interface UploadFileOptions {
  name: string;
  mimeType?: string;
  /** Strings are staged as UTF-8; byte arrays (including Node Buffers) are preserved. */
  content: Uint8Array | string;
}

Property	Type	Required	Readonly	Description
`content`	`string \| Uint8Array<ArrayBufferLike>`	Yes	No	Strings are staged as UTF-8; byte arrays (including Node Buffers) are preserved.
`mimeType`	`string`	No	No	—
`name`	`string`	Yes	No	—

`FileId`

export type FileId = `file_${string}`;

`StagedFileMetadata`

Public metadata returned by the project-scoped staged-file API.

export interface StagedFileMetadata {
  fileId: FileId;
  name: string;
  mimeType: string;
  size: number;
  expiresAt: string;
}

Property	Type	Required	Readonly	Description
`expiresAt`	`string`	Yes	No	—
`fileId`	`file_${string}`	Yes	No	—
`mimeType`	`string`	Yes	No	—
`name`	`string`	Yes	No	—
`size`	`number`	Yes	No	—

`StagedFilePage`

One cursor page of unexpired project-scoped staged-file metadata.

export interface StagedFilePage {
  files: readonly StagedFileMetadata[];
  nextCursor?: string;
}

Property	Type	Required	Readonly	Description
`files`	`readonly StagedFileMetadata[]`	Yes	No	—
`nextCursor`	`string`	No	No	—

`StagedFileReference`

Preferred canonical reference to bytes staged through the files API.

export interface StagedFileReference {
  fileId: FileId;
  /** Optional consumer-visible name overriding the staged metadata. */
  name?: string;
  /** Optional MIME type overriding the staged metadata. */
  mimeType?: string;
}

Property	Type	Required	Readonly	Description
`fileId`	`file_${string}`	Yes	No	—
`mimeType`	`string`	No	No	Optional MIME type overriding the staged metadata.
`name`	`string`	No	No	Optional consumer-visible name overriding the staged metadata.