Method reference

All methods belong to the configured agent client. A ? marks an optional argument or field. Signatures describe types. Examples import the quickstart client. Replace uppercase IDs, file URLs, saved keys, and example revisions before execution. Read the request limits before constructing an AgentRequest. See client configuration for setup and retry behavior.

Responses

responses.answer

Answer a pending clarification or approval. Use the request ID and permitted answers from the current pending input.

Signature

(
  id: string,
  input: {
    input_request_id: string;
    answer: AgentAnswer;
  },
  options?: AgentRequestOptions,
) => Promise<AgentResponseView>;

Example:

import { agent } from "./client.ts";

const result = await agent.responses.answer(
  "RESPONSE_ID",
  {
    input_request_id: "INPUT_REQUEST_ID",
    answer: {
      kind: "approval",
      decision: "approve",
    },
  },
  { idempotencyKey: "SAVED_ANSWER_KEY" },
);
console.log(result);

Guide: responses. Types: AgentAnswer, AgentRequestOptions, AgentResponseView.

responses.cancel

Request server cancellation. Observe the same response to confirm its final state.

Signature

(id: string, options?: AgentRequestOptions) =>
  Promise<AgentResponseView>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.responses.cancel("RESPONSE_ID");
console.log(result);

Guide: responses. Types: AgentRequestOptions, AgentResponseView.

responses.create

Submit a task and return its accepted snapshot. Save the response ID before observing execution.

Signature

(
  request: AgentRequest,
  options?: AgentRequestOptions,
) => Promise<AgentResponseView>;

Example:

import { agent } from "./client.ts";

const result = await agent.responses.create(
  { input: "Generate a blue ceramic mug." },
  { idempotencyKey: "SAVED_COMMAND_KEY" },
);
console.log(result);

Guide: responses. Types: AgentRequest, AgentRequestOptions, AgentResponseView.

responses.retrieve

Read one response snapshot. This method does not wait for execution to finish.

Signature

(id: string, options?: AgentRequestOptions) =>
  Promise<AgentResponseView>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.responses.retrieve("RESPONSE_ID");
console.log(result);

Guide: responses. Types: AgentRequestOptions, AgentResponseView.

responses.selectFinalArtifacts

Save the final artifact selection. Send the current sequence number to detect conflicting writes. Replace the example cursor with the current snapshot sequence.

Signature

(
  id: string,
  input: {
    artifact_ids: string[];
    expected_sequence_number: number;
  },
  options?: AgentResourceOptions,
) => Promise<AgentResponseView>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.responses.selectFinalArtifacts(
    "RESPONSE_ID",
    {
      artifact_ids: ["ARTIFACT_ID"],
      expected_sequence_number: 12,
    },
  );
console.log(result);

Guide: responses. Types: AgentResourceOptions, AgentResponseView.

responses.stream

Stream complete snapshots of an existing response. Replace displayed state on each update.

Signature

(id: string, options?: AgentStreamOptions) =>
  AsyncIterable<AgentResponseView>;

Example:

import { agent } from "./client.ts";

for await (const response of agent.responses.stream(
  "RESPONSE_ID",
)) {
  console.log(response.output_text);
}

Guide: responses. Types: AgentStreamOptions, AgentResponseView.

responses.wait

Poll an existing response until it stops or requires input. A timeout only stops local observation.

Signature

(id: string, options?: AgentRunOptions) =>
  Promise<AgentResponseView>;

Example:

import { agent } from "./client.ts";

const result = await agent.responses.wait(
  "RESPONSE_ID",
  { timeoutMs: 60_000 },
);
console.log(result);

Guide: responses. Types: AgentRunOptions, AgentResponseView.

run

Create a response and poll until execution stops or requires input. This method can incur generation charges.

Signature

(
  request: AgentRequest,
  options?: AgentRunOptions,
) => Promise<AgentResponseView>;

Example:

import { agent } from "./client.ts";

const result = await agent.run({
  input: "Generate a blue ceramic mug.",
});
console.log(result);

Guide: responses. Types: AgentRequest, AgentRunOptions, AgentResponseView.

stream

Create a response and yield complete snapshots. This method starts new work each time you call it.

Signature

(
  request: AgentRequest,
  options?: AgentStreamOptions,
) => AsyncIterable<AgentResponseView>;

Example:

import { agent } from "./client.ts";

for await (const response of agent.stream({
  input: "Generate a blue ceramic mug.",
})) {
  console.log(response.output_text);
}

Guide: responses. Types: AgentRequest, AgentStreamOptions, AgentResponseView.

Conversations

conversations.create

Create an idle conversation. An omitted title or null title leaves the conversation untitled.

Signature

(
  input?: { title?: string | null },
  options?: AgentResourceOptions,
) => Promise<AgentConversation>;

Example:

import { agent } from "./client.ts";

const result = await agent.conversations.create({
  title: "Product campaign",
});
console.log(result);

Guide: resources. Types: AgentResourceOptions, AgentConversation.

conversations.delete

Delete a conversation. Repeat the request when deleted is false, after running work stops.

Signature

(id: string, options?: AgentRequestOptions) =>
  Promise<{ id: string; deleted: boolean }>;

Example:

import { agent } from "./client.ts";

const result = await agent.conversations.delete(
  "CONVERSATION_ID",
);
console.log(result);

Guide: resources. Types: AgentRequestOptions.

conversations.fork

Copy settled conversation history into a new conversation. Set atMessageId to copy through that message’s completed turn. Active turns are excluded. Project placement completes asynchronously.

Signature

(
  id: string,
  input?: {
    atMessageId?: string;
    createProject?: boolean;
  },
  options?: AgentResourceOptions,
) => Promise<AgentConversation>;

Example:

import { agent } from "./client.ts";

const fork = await agent.conversations.fork(
  "CONVERSATION_ID",
  {
    atMessageId: "MESSAGE_ID",
  },
);
console.log(fork.id);

Guide: resources. Types: AgentResourceOptions, AgentConversation.

conversations.generationSummary

Read billed generation costs and counts. Nano-USD totals exclude unpriced requests and LLM usage.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentGenerationSummary>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.conversations.generationSummary(
    "CONVERSATION_ID",
  );
console.log(result);

Guide: resources. Types: AgentResourceOptions, AgentGenerationSummary.

conversations.items.list

Read conversation history with cursor pagination. Restart pagination after a snapshot conflict.

Signature

(id: string, options?: AgentPageOptions) =>
  Promise<AgentPage<AgentConversationItem>>;

Example:

import { agent } from "./client.ts";

const result = await agent.conversations.items.list(
  "CONVERSATION_ID",
  { limit: 20 },
);
console.log(result);

Guide: resources. Types: AgentPageOptions, AgentPage, AgentConversationItem.

conversations.list

List conversations with cursor pagination. Use next_cursor for the next page.

Signature

(options?: AgentPageOptions) =>
  Promise<AgentPage<AgentConversation>>;

Example:

import { agent } from "./client.ts";

const result = await agent.conversations.list({
  limit: 20,
});
console.log(result);

Guide: resources. Types: AgentPageOptions, AgentPage, AgentConversation.

conversations.retrieve

Read a conversation’s title and active response IDs.

Signature

(id: string, options?: AgentRequestOptions) =>
  Promise<AgentConversation>;

Example:

import { agent } from "./client.ts";

const result = await agent.conversations.retrieve(
  "CONVERSATION_ID",
);
console.log(result);

Guide: resources. Types: AgentRequestOptions, AgentConversation. Read the conversation’s share policy, or null if none exists. The policy ID identifies its /chat/share/ link on the fal website. Empty recipient lists allow anyone with the link.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentConversationSharePolicy | null>;

Example:

import { agent } from "./client.ts";

const share =
  await agent.conversations.sharing.retrieve(
    "CONVERSATION_ID",
  );
console.log(share?.policy);

Guide: resources. Types: AgentResourceOptions, AgentConversationSharePolicy. Create or replace the conversation’s share policy. Specify account IDs or email addresses to restrict access. Empty recipients make the link public. expiresAt accepts an ISO 8601 timestamp; omit it or pass null to remove expiration.

Signature

(
  id: string,
  input: AgentConversationSharingInput,
  options?: AgentResourceOptions,
) => Promise<AgentConversationSharePolicy>;

Example:

import { agent } from "./client.ts";

const share =
  await agent.conversations.sharing.update(
    "CONVERSATION_ID",
    { emails: ["reviewer@example.com"] },
  );
console.log(share.id);

Guide: resources. Types: AgentConversationSharingInput, AgentResourceOptions, AgentConversationSharePolicy.

conversations.update

Rename a conversation. Read it after an uncertain acknowledgement before repeating the write.

Signature

(
  id: string,
  change: { title: string },
  options?: AgentRequestOptions,
) => Promise<AgentConversation>;

Example:

import { agent } from "./client.ts";

const result = await agent.conversations.update(
  "CONVERSATION_ID",
  { title: "Mug concepts" },
);
console.log(result);

Guide: resources. Types: AgentRequestOptions, AgentConversation.

Plans

plans.retrieve

Read a plan block within its owning conversation.

Signature

(
  id: string,
  options: AgentRequestOptions & {
    conversation: string;
  },
) => Promise<AgentPlanBlock>;

Example:

import { agent } from "./client.ts";

const result = await agent.plans.retrieve(
  "PLAN_ID",
  { conversation: "CONVERSATION_ID" },
);
console.log(result);

Guide: plans. Types: AgentRequestOptions, AgentPlanBlock.

plans.run

Run a plan at its current revision. Replace the example revision with the value returned by plans.retrieve. Save an idempotency key before submission.

Signature

(
  id: string,
  input: {
    conversation: string;
    expected_revision: number;
  },
  options?: AgentRequestOptions,
) => Promise<AgentResponseView>;

Example:

import { agent } from "./client.ts";

const result = await agent.plans.run(
  "PLAN_ID",
  {
    conversation: "CONVERSATION_ID",
    expected_revision: 3,
  },
  { idempotencyKey: "SAVED_PLAN_KEY" },
);
console.log(result);

Guide: plans. Types: AgentRequestOptions, AgentResponseView.

plans.update

Replace the editable step list at the specified revision. Preserve step IDs to retain existing steps. The example replaces the complete list with one step at revision 3.

Signature

(
  id: string,
  change: AgentPlanUpdate,
  options?: AgentRequestOptions,
) => Promise<AgentPlanBlock>;

Example:

import { agent } from "./client.ts";

const result = await agent.plans.update(
  "PLAN_ID",
  {
    conversation: "CONVERSATION_ID",
    expected_revision: 3,
    steps: [
      {
        id: "STEP_ID",
        label: "Generate a product photo",
        model_pinned: false,
        requires_approval: true,
      },
    ],
  },
  { idempotencyKey: "SAVED_EDIT_KEY" },
);
console.log(result);

Guide: plans. Types: AgentPlanUpdate, AgentRequestOptions, AgentPlanBlock.

Artifacts

artifacts.retrieve

Read an artifact. Omit revision for the available current version.

Signature

(
  id: string,
  options?: AgentRequestOptions & { revision?: 1 },
) => Promise<AgentArtifact>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.artifacts.retrieve("ARTIFACT_ID");
console.log(result);

Guide: media. Types: AgentRequestOptions, AgentArtifact.

Projects

projects.assets.attach

Attach an existing asset to a project. Use its assetId or library assetRecordId.

Signature

(
  id: string,
  assetId: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result = await agent.projects.assets.attach(
  "PROJECT_ID",
  "ASSET_ID",
);
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.assets.detach

Detach an asset from a project without deleting its source file.

Signature

(
  id: string,
  assetId: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result = await agent.projects.assets.detach(
  "PROJECT_ID",
  "ASSET_ID",
);
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.collections.attach

Attach an existing collection to a project.

Signature

(
  id: string,
  collectionId: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.collections.attach(
    "PROJECT_ID",
    "COLLECTION_ID",
  );
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.collections.detach

Remove a collection’s project association.

Signature

(
  id: string,
  collectionId: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.collections.detach(
    "PROJECT_ID",
    "COLLECTION_ID",
  );
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.conversations.add

Add an existing conversation to a project.

Signature

(
  id: string,
  conversation: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.conversations.add(
    "PROJECT_ID",
    "CONVERSATION_ID",
  );
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.conversations.create

Create an idle conversation within a project.

Signature

(
  id: string,
  input?: { title?: string | null },
  options?: AgentResourceOptions,
) => Promise<AgentConversation>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.conversations.create(
    "PROJECT_ID",
    { title: "Product concepts" },
  );
console.log(result);

Guide: projects. Types: AgentResourceOptions, AgentConversation.

projects.conversations.list

List visible conversations in a project. This method returns an array without a pagination cursor.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentProjectConversation[]>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.conversations.list(
    "PROJECT_ID",
  );
console.log(result);

Guide: projects. Types: AgentResourceOptions, AgentProjectConversation.

projects.conversations.remove

Remove a conversation’s project association. This does not delete the conversation.

Signature

(
  id: string,
  conversation: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.conversations.remove(
    "PROJECT_ID",
    "CONVERSATION_ID",
  );
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.conversations.setMemoryPrivacy

Set excluded to true to exclude the conversation from project memory. The conversation must belong to the project.

Signature

(
  id: string,
  conversation: string,
  excluded: boolean,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.conversations.setMemoryPrivacy(
    "PROJECT_ID",
    "CONVERSATION_ID",
    true,
  );
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.create

Create a project with a name and optional color.

Signature

(
  input: { name: string; color?: string },
  options?: AgentResourceOptions,
) => Promise<AgentProject>;

Example:

import { agent } from "./client.ts";

const result = await agent.projects.create({
  name: "Autumn campaign",
});
console.log(result);

Guide: projects. Types: AgentResourceOptions, AgentProject.

projects.delete

Delete the project association and project-scoped resources. This does not delete its conversations or source media.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.delete("PROJECT_ID");
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.documents.attach

Attach a fal storage URL and extracted text. Replace the sample file URL, metadata, and text with your uploaded document.

Signature

(
  id: string,
  input: AgentProjectDocumentInput,
  options?: AgentResourceOptions,
) => Promise<AgentProjectDocument>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.documents.attach(
    "PROJECT_ID",
    {
      url: "https://fal.media/files/FILE_ID/brief.txt",
      fileName: "brief.txt",
      contentType: "text/plain",
      sizeBytes: 16,
      text: "Blue background.",
    },
  );
console.log(result);

Guide: projects. Types: AgentProjectDocumentInput, AgentResourceOptions, AgentProjectDocument.

projects.documents.import

Extract and attach a document already uploaded to supported fal storage. The server downloads at most 25 MiB without following redirects. MIME type can be inferred from the filename. PDF and DOCX text is extracted automatically. Empty documents have no_text status.

Signature

(
  id: string,
  input: AgentProjectDocumentImport,
  options?: AgentResourceOptions,
) => Promise<AgentProjectDocument>;

Example:

import { agent } from "./client.ts";

const document =
  await agent.projects.documents.import(
    "project_id",
    {
      url: "https://fal.media/files/brief.pdf",
      fileName: "brief.pdf",
    },
  );
console.log(document.status);

Guide: projects. Types: AgentProjectDocumentImport, AgentResourceOptions, AgentProjectDocument.

projects.documents.list

List project documents and their processing status.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentProjectDocument[]>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.documents.list("PROJECT_ID");
console.log(result);

Guide: projects. Types: AgentResourceOptions, AgentProjectDocument.

projects.documents.preview

Read a document’s extracted text. Use the document’s assetId.

Signature

(
  id: string,
  assetId: string,
  options?: AgentResourceOptions,
) => Promise<{ text: string; truncated: boolean }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.documents.preview(
    "PROJECT_ID",
    "ASSET_ID",
  );
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.documents.remove

Remove the document from the project. Use the document’s assetId.

Signature

(
  id: string,
  assetId: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.documents.remove(
    "PROJECT_ID",
    "ASSET_ID",
  );
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.documents.retry

Retry document processing. Read its status after submission.

Signature

(
  id: string,
  assetId: string,
  options?: AgentResourceOptions,
) => Promise<AgentProjectDocument>;

Example:

import { agent } from "./client.ts";

const result = await agent.projects.documents.retry(
  "PROJECT_ID",
  "ASSET_ID",
);
console.log(result);

Guide: projects. Types: AgentResourceOptions, AgentProjectDocument.

projects.documents.upload

Upload a document, extract its text, and attach it to a project. Supports PDF, DOCX, and text files up to 25 MiB. Ingestion continues in the background; poll documents.list for its status. Uploads use fal storage credentials configured on the client. Aborting observation does not undo an uploaded file.

Signature

(
  id: string,
  file: File,
  options?: AgentResourceOptions,
) => Promise<AgentProjectDocument>;

Example:

import { agent } from "./client.ts";

const file = new File(
  ["Use warm colors."],
  "brief.txt",
  {
    type: "text/plain",
  },
);
const document =
  await agent.projects.documents.upload(
    "project_id",
    file,
  );
console.log(document.status);

Guide: projects. Types: AgentResourceOptions, AgentProjectDocument.

projects.list

List project summaries, including counts and cover media.

Signature

(options?: AgentResourceOptions) =>
  Promise<AgentProjectSummary[]>;

Example:

import { agent } from "./client.ts";

const result = await agent.projects.list();
console.log(result);

Guide: projects. Types: AgentResourceOptions, AgentProjectSummary.

projects.memory.create

Create a memory note. supersededId identifies a note replaced by this operation, when present.

Signature

(
  id: string,
  input: { kind: AgentMemoryKind; content: string },
  options?: AgentResourceOptions,
) =>
  Promise<{
    id: string;
    supersededId: string | null;
  }>;

Example:

import { agent } from "./client.ts";

const result = await agent.projects.memory.create(
  "PROJECT_ID",
  {
    kind: "style",
    content: "Use a blue background.",
  },
);
console.log(result);

Guide: projects. Types: AgentMemoryKind, AgentResourceOptions.

projects.memory.retrieve

Read the project’s primer and active memory notes.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentProjectMemory>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.memory.retrieve(
    "PROJECT_ID",
  );
console.log(result);

Guide: projects. Types: AgentResourceOptions, AgentProjectMemory.

projects.memory.update

Edit, pin, delete, or restore a memory note within the project.

Signature

(
  id: string,
  noteId: string,
  input: {
    content?: string;
    pinned?: boolean;
    status?: "active" | "deleted";
  },
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result = await agent.projects.memory.update(
  "PROJECT_ID",
  "NOTE_ID",
  { pinned: true },
);
console.log(result);

Guide: projects. Types: AgentResourceOptions.

projects.resources

Read attached media, collections, characters, smart entities, and generated media.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentProjectResources>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.resources("PROJECT_ID");
console.log(result);

Guide: projects. Types: AgentResourceOptions, AgentProjectResources.

projects.retrieve

Read project identity, name, color, and creation time.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentProject>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.projects.retrieve("PROJECT_ID");
console.log(result);

Guide: projects. Types: AgentResourceOptions, AgentProject.

projects.update

Change a project’s name, color, or both. Supply at least one field.

Signature

(
  id: string,
  input: { name?: string; color?: string },
  options?: AgentResourceOptions,
) => Promise<AgentProject>;

Example:

import { agent } from "./client.ts";

const result = await agent.projects.update(
  "PROJECT_ID",
  { name: "Winter campaign" },
);
console.log(result);

Guide: projects. Types: AgentResourceOptions, AgentProject.

Models

models.capabilities

Read a generation model’s configurable fields, required flags, and default values.

Signature

(
  endpointId: string,
  options?: AgentResourceOptions,
) => Promise<AgentModelCapabilities>;

Example:

import { agent } from "./client.ts";

const result = await agent.models.capabilities(
  "MODEL_ENDPOINT_ID",
);
console.log(result);

Guide: settings. Types: AgentResourceOptions, AgentModelCapabilities.

models.list

Search generation models. Use page-based pagination, not a history cursor.

Signature

(
  filter?: {
    keywords?: string;
    categories?: string[];
    page?: number;
    limit?: number;
  },
  options?: AgentResourceOptions,
) =>
  Promise<{
    items: AgentModel[];
    total?: number | null;
    page?: number;
    size?: number;
    pages?: number | null;
  }>;

Example:

import { agent } from "./client.ts";

const result = await agent.models.list({
  keywords: "image",
  page: 1,
  limit: 10,
});
console.log(result);

Guide: settings. Types: AgentResourceOptions, AgentModel.

models.listAgentModels

List available reasoning models. Use these IDs for the defaultModel account preference.

Signature

(options?: AgentResourceOptions) =>
  Promise<
    {
      id: string;
      label: string;
      tag?: "recommended" | "experimental";
    }[]
  >;

Example:

import { agent } from "./client.ts";

const result = await agent.models.listAgentModels();
console.log(result);

Guide: settings. Types: AgentResourceOptions.

Settings

settings.conversations.retrieve

Read generation settings for a conversation.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentGenerationSettings>;

Example:

import { agent } from "./client.ts";

const settings =
  await agent.settings.conversations.retrieve(
    "CONVERSATION_ID",
  );
console.log(settings);

Guide: settings. Types: AgentResourceOptions, AgentGenerationSettings.

settings.conversations.update

Replace conversation settings with the expected revision. Preserve unrelated fields from the latest read.

Signature

(
  id: string,
  input: {
    settings: AgentGenerationSettings;
    expectedRevision: number;
  },
  options?: AgentResourceOptions,
) => Promise<AgentGenerationSettings>;

Example:

import { agent } from "./client.ts";

const settings =
  await agent.settings.conversations.retrieve(
    "CONVERSATION_ID",
  );
const result =
  await agent.settings.conversations.update(
    "CONVERSATION_ID",
    {
      settings: {
        ...settings,
        reviewBeforeGenerating: true,
      },
      expectedRevision: settings.revision,
    },
  );
console.log(result);

Guide: settings. Types: AgentGenerationSettings, AgentResourceOptions.

settings.defaults.retrieve

Read local, inherited, and effective generation defaults with their sources.

Signature

(
  target: AgentDefaultsTarget,
  options?: AgentResourceOptions,
) => Promise<AgentDefaultsView>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.settings.defaults.retrieve({
    scope: "personal",
  });
console.log(result);

Guide: settings. Types: AgentDefaultsTarget, AgentResourceOptions, AgentDefaultsView.

settings.defaults.update

Change or inherit defaults. Send the last local object as expectedLocal to detect conflicting edits.

Signature

(
  target: AgentDefaultsTarget,
  input: AgentDefaultsUpdate,
  options?: AgentResourceOptions,
) => Promise<AgentDefaultsView>;

Example:

import { agent } from "./client.ts";

const target = { scope: "personal" } as const;
const defaults =
  await agent.settings.defaults.retrieve(target);
const result = await agent.settings.defaults.update(
  target,
  {
    expectedLocal: defaults.local,
    changes: {
      preferences: { aspect_ratio: "16:9" },
      preferredModels: {},
    },
  },
);
console.log(result.effective);

Guide: settings. Types: AgentDefaultsTarget, AgentDefaultsUpdate, AgentResourceOptions, AgentDefaultsView.

settings.projects.retrieve

Read generation settings saved on a project.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentGenerationSettings>;

Example:

import { agent } from "./client.ts";

const settings =
  await agent.settings.projects.retrieve(
    "PROJECT_ID",
  );
console.log(settings);

Guide: settings. Types: AgentResourceOptions, AgentGenerationSettings.

settings.projects.update

Replace project settings with the expected revision. Preserve unrelated fields from the latest read.

Signature

(
  id: string,
  input: {
    settings: AgentGenerationSettings;
    expectedRevision: number;
  },
  options?: AgentResourceOptions,
) => Promise<AgentGenerationSettings>;

Example:

import { agent } from "./client.ts";

const settings =
  await agent.settings.projects.retrieve(
    "PROJECT_ID",
  );
const result = await agent.settings.projects.update(
  "PROJECT_ID",
  {
    settings: {
      ...settings,
      reviewBeforeGenerating: true,
    },
    expectedRevision: settings.revision,
  },
);
console.log(result);

Guide: settings. Types: AgentGenerationSettings, AgentResourceOptions.

Preferences

preferences.retrieve

Read account preferences, including generation defaults.

Signature

(options?: AgentResourceOptions) =>
  Promise<AgentPreferences>;

Example:

import { agent } from "./client.ts";

const result = await agent.preferences.retrieve();
console.log(result);

Guide: settings. Types: AgentResourceOptions, AgentPreferences.

preferences.update

Update fields within one preference section. The section determines the accepted input fields.

Signature

<
  S extends
    | "general"
    | "cost"
    | "skills"
    | "notifications",
>(
  section: S,
  input: Partial<AgentPreferences[S]>,
  options?: AgentResourceOptions,
) => Promise<AgentPreferences>;

Example:

import { agent } from "./client.ts";

const result = await agent.preferences.update(
  "notifications",
  { turnComplete: false },
);
console.log(result);

Guide: settings. Types: AgentPreferences, AgentResourceOptions.

Queue

queue.cancel

Cancel a queued turn by its turn ID.

Signature

(
  conversation: string,
  turnId: string,
  options?: AgentResourceOptions,
) => Promise<{ success: boolean }>;

Example:

import { agent } from "./client.ts";

const result = await agent.queue.cancel(
  "CONVERSATION_ID",
  "TURN_ID",
);
console.log(result);

Guide: queue. Types: AgentResourceOptions.

queue.dispatch

Attempt to dispatch eligible queued work. promoted false means this call did not start a turn.

Signature

(
  conversation: string,
  options?: AgentResourceOptions,
) => Promise<AgentQueueDispatch>;

Example:

import { agent } from "./client.ts";

const result = await agent.queue.dispatch(
  "CONVERSATION_ID",
);
console.log(result);

Guide: queue. Types: AgentResourceOptions, AgentQueueDispatch.

queue.edit

Replace a queued prompt with 1–10,000 characters. This does not edit a running response.

Signature

(
  conversation: string,
  turnId: string,
  content: string,
  options?: AgentResourceOptions,
) => Promise<{ success: boolean }>;

Example:

import { agent } from "./client.ts";

const result = await agent.queue.edit(
  "CONVERSATION_ID",
  "TURN_ID",
  "Use a blue background.",
);
console.log(result);

Guide: queue. Types: AgentResourceOptions.

queue.reorder

Reorder queued turns by turn ID. Supply at most 50 IDs. Steps within a plan retain their required order. Retrieve the queue for its effective order.

Signature

(
  conversation: string,
  turnIds: string[],
  options?: AgentResourceOptions,
) => Promise<{ success: boolean }>;

Example:

import { agent } from "./client.ts";

const result = await agent.queue.reorder(
  "CONVERSATION_ID",
  ["TURN_ID_1", "TURN_ID_2"],
);
console.log(result);

Guide: queue. Types: AgentResourceOptions.

queue.retrieve

Read queued turns and active turn IDs for a conversation.

Signature

(
  conversation: string,
  options?: AgentResourceOptions,
) =>
  Promise<{
    items: AgentQueueItem[];
    active_turn_ids: string[];
  }>;

Example:

import { agent } from "./client.ts";

const result = await agent.queue.retrieve(
  "CONVERSATION_ID",
);
console.log(result);

Guide: queue. Types: AgentResourceOptions, AgentQueueItem.

queue.run

Request immediate execution of a queued turn. This can bypass its normal queue position.

Signature

(
  conversation: string,
  turnId: string,
  options?: AgentResourceOptions,
) => Promise<AgentQueueDispatch>;

Example:

import { agent } from "./client.ts";

const result = await agent.queue.run(
  "CONVERSATION_ID",
  "TURN_ID",
);
console.log(result);

Guide: queue. Types: AgentResourceOptions, AgentQueueDispatch.

queue.setApproval

Change a continuation’s approval requirement. Removing the requirement can dispatch work immediately.

Signature

(
  conversation: string,
  turnId: string,
  input: {
    requiresApproval: boolean;
    approveCheckpoints?: boolean;
  },
  options?: AgentResourceOptions,
) =>
  Promise<{
    updated: boolean;
    dispatch: AgentQueueDispatch | null;
  }>;

Example:

import { agent } from "./client.ts";

const result = await agent.queue.setApproval(
  "CONVERSATION_ID",
  "TURN_ID",
  { requiresApproval: true },
);
console.log(result);

Guide: queue. Types: AgentResourceOptions, AgentQueueDispatch.

queue.setHalted

Pause or resume queue dispatch. Resuming also attempts to dispatch eligible work.

Signature

(
  conversation: string,
  halted: boolean,
  options?: AgentResourceOptions,
) =>
  Promise<{
    updatedCount: number;
    dispatch: AgentQueueDispatch | null;
  }>;

Example:

import { agent } from "./client.ts";

const result = await agent.queue.setHalted(
  "CONVERSATION_ID",
  true,
);
console.log(result);

Guide: queue. Types: AgentResourceOptions, AgentQueueDispatch.

Runs

runs.answer

Answer a cost approval from the retrieved run. The decision applies to its approval group.

Signature

(
  id: string,
  conversation: string,
  input: {
    input_request_id: string;
    decision: "approve" | "reject";
  },
  options?: AgentResourceOptions,
) =>
  Promise<{
    submittedCount?: number;
    failedCount?: number;
    cancelledCount?: number;
  }>;

Example:

import { agent } from "./client.ts";

const result = await agent.runs.answer(
  "RUN_ID",
  "CONVERSATION_ID",
  {
    input_request_id: "INPUT_REQUEST_ID",
    decision: "approve",
  },
);
console.log(result);

Guide: queue. Types: AgentResourceOptions.

runs.cancel

Request cancellation of a generation run. Inspect cancelled and retrieve the run afterward.

Signature

(
  id: string,
  conversation: string,
  options?: AgentResourceOptions,
) => Promise<{ cancelled: boolean }>;

Example:

import { agent } from "./client.ts";

const result = await agent.runs.cancel(
  "RUN_ID",
  "CONVERSATION_ID",
);
console.log(result);

Guide: queue. Types: AgentResourceOptions.

runs.retrieve

Read a generation run’s operation, artifacts, and pending cost approvals.

Signature

(
  id: string,
  conversation: string,
  options?: AgentResourceOptions,
) => Promise<AgentRunView>;

Example:

import { agent } from "./client.ts";

const result = await agent.runs.retrieve(
  "RUN_ID",
  "CONVERSATION_ID",
);
console.log(result);

Guide: queue. Types: AgentResourceOptions, AgentRunView.

runs.retry

Request another generation attempt. This can incur charges and require a new approval.

Signature

(
  id: string,
  conversation: string,
  options?: AgentResourceOptions,
) =>
  Promise<{
    mediaId: string;
    runId: string;
    attempt: number;
    requestId: string;
    approvalRequired?: boolean;
  }>;

Example:

import { agent } from "./client.ts";

const result = await agent.runs.retry(
  "RUN_ID",
  "CONVERSATION_ID",
);
console.log(result);

Guide: queue. Types: AgentResourceOptions.

Library

library.assets.assignTag

Assign an existing tag to an asset record.

Signature

(
  id: string,
  tagId: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

await agent.library.assets.assignTag(
  "ASSET_RECORD_ID",
  "TAG_ID",
);

Guide: library. Types: AgentResourceOptions.

library.assets.delete

Delete a library asset using its assetRecordId.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result = await agent.library.assets.delete(
  "ASSET_RECORD_ID",
);
console.log(result);

Guide: library. Types: AgentResourceOptions.

library.assets.list

Search library assets. Follow nextCursor and inspect scopeTruncated before treating the result as complete.

Signature

(
  input?: AgentLibraryAssetQuery,
  options?: AgentResourceOptions,
) =>
  Promise<{
    items: AgentLibraryAsset[];
    nextCursor: string | null;
    totalCount: number | null;
    scopeTruncated: boolean;
  }>;

Example:

import { agent } from "./client.ts";

const result = await agent.library.assets.list({
  mediaTypes: ["image"],
  limit: 20,
});
console.log(result);

Guide: library. Types: AgentLibraryAssetQuery, AgentResourceOptions, AgentLibraryAsset.

library.assets.register

Signature

(
  input: {
    url: string;
    type: AgentLibraryMediaType;
    size?: number;
    collectionId?: string | null;
    favorite?: boolean;
  },
  options?: AgentResourceOptions,
) => Promise<AgentLibraryAsset>;

Example:

import { agent } from "./client.ts";

const result = await agent.library.assets.register({
  url: "https://fal.media/files/FILE_ID/mug.png",
  type: "image",
});
console.log(result);

Guide: library. Types: AgentLibraryMediaType, AgentResourceOptions, AgentLibraryAsset.

library.assets.removeTag

Remove a tag assignment without deleting the tag or asset.

Signature

(
  id: string,
  tagId: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

await agent.library.assets.removeTag(
  "ASSET_RECORD_ID",
  "TAG_ID",
);

Guide: library. Types: AgentResourceOptions.

library.assets.retrieve

Read asset metadata using its library assetRecordId.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentLibraryAsset>;

Example:

import { agent } from "./client.ts";

const result = await agent.library.assets.retrieve(
  "ASSET_RECORD_ID",
);
console.log(result);

Guide: library. Types: AgentResourceOptions, AgentLibraryAsset.

library.assets.setFavorite

Set an asset’s favorite state using its assetRecordId.

Signature

(
  id: string,
  favorite: boolean,
  options?: AgentResourceOptions,
) =>
  Promise<{
    assetRecordId: string;
    assetId: null;
    isFavorited: boolean;
  }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.library.assets.setFavorite(
    "ASSET_RECORD_ID",
    true,
  );
console.log(result);

Guide: library. Types: AgentResourceOptions.

library.assets.tags

Read the tags assigned to an asset record.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentLibraryTag[]>;

Example:

import { agent } from "./client.ts";

const tags = await agent.library.assets.tags(
  "ASSET_RECORD_ID",
);
console.log(tags);

Guide: library. Types: AgentResourceOptions, AgentLibraryTag.

library.assets.updatePrompt

Update an uploaded asset’s prompt with 1–2,000 characters. Generated assets do not support this operation.

Signature

(
  id: string,
  prompt: string,
  options?: AgentResourceOptions,
) => Promise<AgentLibraryAsset>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.library.assets.updatePrompt(
    "ASSET_RECORD_ID",
    "Blue ceramic mug",
  );
console.log(result);

Guide: library. Types: AgentResourceOptions, AgentLibraryAsset.

library.characters.checkIdentifier

Normalize a proposed character identifier and check availability. Creation can still fail if another request takes it first.

Signature

(
  identifier: string,
  options?: AgentResourceOptions,
) =>
  Promise<{
    identifier: string;
    available: boolean;
  }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.library.characters.checkIdentifier(
    "milo",
  );
console.log(result);

Guide: library. Types: AgentResourceOptions.

library.characters.create

Create a character from a description and one to twenty reference images. References accept fal-hosted URLs or existing asset targets.

Signature

(
  input: AgentCharacterInput & {
    identifier?: string;
  },
  options?: AgentResourceOptions,
) =>
  Promise<
    AgentLibraryCollection & { type: "character" }
  >;

Example:

import { agent } from "./client.ts";

const character =
  await agent.library.characters.create({
    name: "Milo",
    identifier: "milo",
    description: "A gray cat with green eyes.",
    referenceImages: [
      "https://fal.media/files/REFERENCE.png",
    ],
  });
console.log(character);

Guide: library. Types: AgentCharacterInput, AgentResourceOptions, AgentLibraryCollection.

library.characters.references

Read reference image URLs and asset record IDs. Exclude entries with isCover when saving the reference list.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentCharacterReference[]>;

Example:

import { agent } from "./client.ts";

const references =
  await agent.library.characters.references(
    "CHARACTER_ID",
  );
console.log(references);

Guide: library. Types: AgentResourceOptions, AgentCharacterReference.

library.characters.update

Replace a character name, description, and complete reference list. Character identifiers cannot be changed.

Signature

(
  id: string,
  input: AgentCharacterInput,
  options?: AgentResourceOptions,
) =>
  Promise<
    AgentLibraryCollection & { type: "character" }
  >;

Example:

import { agent } from "./client.ts";

const character =
  await agent.library.characters.update(
    "CHARACTER_ID",
    {
      name: "Milo",
      description: "A gray cat with green eyes.",
      referenceImages: [
        "https://fal.media/files/REFERENCE.png",
      ],
    },
  );
console.log(character);

Guide: library. Types: AgentCharacterInput, AgentResourceOptions, AgentLibraryCollection.

library.collections.addAsset

Add an asset to a manual collection or smart entity gallery. Use the assetRecordId. This does not change defining references.

Signature

(
  id: string,
  assetRecordId: string,
  options?: AgentResourceOptions,
) =>
  Promise<{
    collectionId: string;
    assetRecordId: string;
  }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.library.collections.addAsset(
    "COLLECTION_ID",
    "ASSET_RECORD_ID",
  );
console.log(result);

Guide: library. Types: AgentResourceOptions.

library.collections.create

Create a manual collection or a smart collection with filters.

Signature

(
  input: AgentCollectionInput,
  options?: AgentResourceOptions,
) => Promise<AgentLibraryCollection>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.library.collections.create({
    name: "Mugs",
  });
console.log(result);

Guide: library. Types: AgentCollectionInput, AgentResourceOptions, AgentLibraryCollection.

library.collections.delete

Delete a collection or smart entity through the shared product operation. This does not delete its source assets.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.library.collections.delete(
    "COLLECTION_ID",
  );
console.log(result);

Guide: library. Types: AgentResourceOptions.

library.collections.list

List collections with offset pagination. includeCharacters preserves character inclusion. Set includeSmartEntities to true to include all five entity types.

Signature

(
  input?: {
    limit?: number;
    offset?: number;
    includeCharacters?: boolean;
    includeSmartEntities?: boolean;
  },
  options?: AgentResourceOptions,
) => Promise<AgentLibraryCollection[]>;

Example:

import { agent } from "./client.ts";

const result = await agent.library.collections.list(
  {
    limit: 20,
    offset: 0,
    includeSmartEntities: true,
  },
);
console.log(result);

Guide: library. Types: AgentResourceOptions, AgentLibraryCollection.

library.collections.move

Move a collection under a parent. Use null to move it to the root.

Signature

(
  id: string,
  parentCollectionId: string | null,
  options?: AgentResourceOptions,
) => Promise<AgentLibraryCollection>;

Example:

import { agent } from "./client.ts";

const result = await agent.library.collections.move(
  "COLLECTION_ID",
  null,
);
console.log(result);

Guide: library. Types: AgentResourceOptions, AgentLibraryCollection.

library.collections.removeAsset

Remove a manual collection membership or smart entity gallery link. Assets, defining references, and recorded generation usage are preserved.

Signature

(
  id: string,
  assetRecordId: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.library.collections.removeAsset(
    "COLLECTION_ID",
    "ASSET_RECORD_ID",
  );
console.log(result);

Guide: library. Types: AgentResourceOptions.

library.collections.setFavorite

Set a collection or smart entity’s favorite state.

Signature

(
  id: string,
  favorite: boolean,
  options?: AgentResourceOptions,
) => Promise<AgentLibraryCollection>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.library.collections.setFavorite(
    "COLLECTION_ID",
    true,
  );
console.log(result);

Guide: library. Types: AgentResourceOptions, AgentLibraryCollection.

library.collections.update

Update collection metadata or filters. Use null to clear nullable fields.

Signature

(
  id: string,
  input: {
    name?: string;
    description?: string | null;
    icon?: string | null;
    color?: string | null;
    coverImageUrl?: string | null;
    filters?: AgentCollectionFilter | null;
  },
  options?: AgentResourceOptions,
) => Promise<AgentLibraryCollection>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.library.collections.update(
    "COLLECTION_ID",
    { description: "Ceramic mug concepts" },
  );
console.log(result);

Guide: library. Types: AgentCollectionFilter, AgentResourceOptions, AgentLibraryCollection.

library.entities.addAsset

Link an existing asset to an entity gallery. This does not change its defining reference images.

Signature

(
  id: string,
  assetRef: string,
  options?: AgentResourceOptions,
) =>
  Promise<{
    smartEntityId: string;
    assetRecordId: string;
  }>;

Example:

import { agent } from "./client.ts";

await agent.library.entities.addAsset(
  "ENTITY_ID",
  "ASSET_RECORD_ID",
);

Guide: library. Types: AgentResourceOptions.

library.entities.checkHandle

Normalize a handle and check availability across all five types. Set excludeId when editing. Availability does not reserve the handle.

Signature

(
  input: { handle: string; excludeId?: string },
  options?: AgentResourceOptions,
) =>
  Promise<{
    handle: string;
    available: boolean;
  }>;

Example:

import { agent } from "./client.ts";

const result =
  await agent.library.entities.checkHandle({
    handle: "blue-mug",
    excludeId: "PROP_ID",
  });
console.log(result.handle, result.available);

Guide: library. Types: AgentResourceOptions.

library.entities.create

Create any smart entity type with one to twenty defining references. Characters require a description and reject custom metadata.

Signature

(
  input: AgentLibraryEntityInput,
  options?: AgentResourceOptions,
) => Promise<AgentLibraryEntity>;

Example:

import { agent } from "./client.ts";

const entity = await agent.library.entities.create({
  type: "prop",
  name: "Blue mug",
  handle: "blue-mug",
  referenceImages: [
    "https://fal.media/files/MUG.png",
  ],
});
console.log(entity);

Guide: library. Types: AgentLibraryEntityInput, AgentResourceOptions, AgentLibraryEntity.

library.entities.delete

Delete any smart entity type through the shared product operation. Source assets are preserved.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

await agent.library.entities.delete("ENTITY_ID");

Guide: library. Types: AgentResourceOptions.

library.entities.list

List smart entities with offset pagination. Filter by types or search names and handles. Omit types to include all five entity types.

Signature

(
  input?: AgentLibraryEntityQuery,
  options?: AgentResourceOptions,
) => Promise<AgentLibraryEntity[]>;

Example:

import { agent } from "./client.ts";

const entities = await agent.library.entities.list({
  types: [
    "character",
    "prop",
    "environment",
    "style",
    "scene",
  ],
  limit: 100,
  offset: 0,
});
console.log(entities);

Guide: library. Types: AgentLibraryEntityQuery, AgentResourceOptions, AgentLibraryEntity.

library.entities.listAssets

Read associated media with offset pagination. Set includeReferences to include images whose only association is defining reference membership.

Signature

(
  id: string,
  input?: {
    mediaTypes?: AgentLibraryMediaType[];
    limit?: number;
    offset?: number;
    includeReferences?: boolean;
  },
  options?: AgentResourceOptions,
) =>
  Promise<{
    items: AgentLibraryAsset[];
    nextOffset: number | null;
    totalCount: number;
  }>;

Example:

import { agent } from "./client.ts";

const page =
  await agent.library.entities.listAssets(
    "ENTITY_ID",
    { mediaTypes: ["image"], limit: 50, offset: 0 },
  );
console.log(
  page.items,
  page.nextOffset,
  page.totalCount,
);

Guide: library. Types: AgentLibraryMediaType, AgentResourceOptions, AgentLibraryAsset.

library.entities.removeAsset

Remove a manual gallery link without deleting the asset. Recorded generation usage and defining reference images are preserved.

Signature

(
  id: string,
  assetRef: string,
  options?: AgentResourceOptions,
) => Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

await agent.library.entities.removeAsset(
  "ENTITY_ID",
  "ASSET_RECORD_ID",
);

Guide: library. Types: AgentResourceOptions.

library.entities.resolve

Resolve one to 100 handles within the account. Unknown handles are omitted. Use types to restrict the matching entity types.

Signature

(
  input: {
    handles: string[];
    types?: AgentLibraryEntityType[];
  },
  options?: AgentResourceOptions,
) => Promise<AgentLibraryEntity[]>;

Example:

import { agent } from "./client.ts";

const entities =
  await agent.library.entities.resolve({
    handles: [
      "@milo",
      "@blue-mug",
      "@workshop",
      "@watercolor",
      "@breakfast",
    ],
  });
console.log(entities);

Guide: library. Types: AgentLibraryEntityType, AgentResourceOptions, AgentLibraryEntity.

library.entities.retrieve

Read an entity and its defining reference-image URLs. The references exclude its associated-media gallery.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentLibraryEntity>;

Example:

import { agent } from "./client.ts";

const entity =
  await agent.library.entities.retrieve(
    "ENTITY_ID",
  );
console.log(
  entity.type,
  entity.metadata,
  entity.references,
);

Guide: library. Types: AgentResourceOptions, AgentLibraryEntity.

library.entities.setFavorite

Set the favorite state for any smart entity type.

Signature

(
  id: string,
  favorite: boolean,
  options?: AgentResourceOptions,
) => Promise<AgentLibraryEntity>;

Example:

import { agent } from "./client.ts";

const entity =
  await agent.library.entities.setFavorite(
    "ENTITY_ID",
    true,
  );
console.log(entity);

Guide: library. Types: AgentResourceOptions, AgentLibraryEntity.

library.entities.update

Update entity fields. Supplied references replace the complete defining set. Types and character handles cannot change. Character metadata is managed automatically.

Signature

(
  id: string,
  input: AgentLibraryEntityUpdate,
  options?: AgentResourceOptions,
) => Promise<AgentLibraryEntity>;

Example:

import { agent } from "./client.ts";

const entity = await agent.library.entities.update(
  "PROP_ID",
  {
    description:
      "A blue ceramic mug with a rounded handle.",
    referenceImages: [
      "https://fal.media/files/MUG_FRONT.png",
      "https://fal.media/files/MUG_SIDE.png",
    ],
  },
);
console.log(entity);

Guide: library. Types: AgentLibraryEntityUpdate, AgentResourceOptions, AgentLibraryEntity.

library.tags.create

Create a tag. Names are trimmed and stored in lowercase.

Signature

(
  input: { name: string; color?: string },
  options?: AgentResourceOptions,
) => Promise<AgentLibraryTag>;

Example:

import { agent } from "./client.ts";

const tag = await agent.library.tags.create({
  name: "campaign",
  color: "blue",
});
console.log(tag);

Guide: library. Types: AgentResourceOptions, AgentLibraryTag.

library.tags.delete

Delete a tag and its asset assignments. This does not delete assets.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<{ success: true }>;

Example:

import { agent } from "./client.ts";

await agent.library.tags.delete("TAG_ID");

Guide: library. Types: AgentResourceOptions.

library.tags.list

List available asset tags. System tags are excluded.

Signature

(options?: AgentResourceOptions) =>
  Promise<AgentLibraryTag[]>;

Example:

import { agent } from "./client.ts";

const tags = await agent.library.tags.list();
console.log(tags);

Guide: library. Types: AgentResourceOptions, AgentLibraryTag.

library.tags.update

Change a tag name or color. Tag names must be unique within the account.

Signature

(
  id: string,
  input: { name?: string; color?: string },
  options?: AgentResourceOptions,
) => Promise<AgentLibraryTag>;

Example:

import { agent } from "./client.ts";

const tag = await agent.library.tags.update(
  "TAG_ID",
  { name: "launch" },
);
console.log(tag);

Guide: library. Types: AgentResourceOptions, AgentLibraryTag.

Skills

skills.checkForUpdates

Check an imported skill against its repository default branch. Custom and detached skills cannot check for updates.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<{
    currentSha: string | null;
    latestSha: string;
    hasUpdate: boolean;
  }>;

Example:

import { agent } from "./client.ts";

const update =
  await agent.skills.checkForUpdates("SKILL_ID");
console.log(update.hasUpdate);

Guide: skills. Types: AgentResourceOptions.

skills.create

Create a custom skill. Names use lowercase letters, digits, and hyphens. presetClash reports a matching fal skill.

Signature

(
  input: AgentSkillContent,
  options?: AgentResourceOptions,
) =>
  Promise<{
    skill: AgentInstalledSkill;
    presetClash: boolean;
  }>;

Example:

import { agent } from "./client.ts";

const { skill } = await agent.skills.create({
  name: "product-photos",
  description: "Create consistent product photos.",
  body: "Preserve the product shape and colors.",
});
console.log(skill.id);

Guide: skills. Types: AgentSkillContent, AgentResourceOptions, AgentInstalledSkill.

skills.importFromGithub

Import a skill from a public GitHub repository. Script-based skills are unsupported.

Signature

(
  input: AgentSkillSource,
  options?: AgentResourceOptions,
) => Promise<AgentInstalledSkill>;

Example:

import { agent } from "./client.ts";

const skill = await agent.skills.importFromGithub({
  repoUrl: "https://github.com/OWNER/REPO",
  subpath: "skills/photo-editing",
});
console.log(skill.id);

Guide: skills. Types: AgentSkillSource, AgentResourceOptions, AgentInstalledSkill.

skills.list

List fal skills and your installed skills. Disabled and shadowed flags explain which skills are available.

Signature

(
  filter?: {
    search?: string;
    conversationId?: string;
  },
  options?: AgentResourceOptions,
) => Promise<AgentSkill[]>;

Example:

import { agent } from "./client.ts";

const skills = await agent.skills.list();
console.log(skills);

Guide: skills. Types: AgentResourceOptions, AgentSkill.

skills.previewImport

Inspect a public GitHub skill before importing it. Check scripts and name conflicts before continuing.

Signature

(
  input: AgentSkillSource,
  options?: AgentResourceOptions,
) => Promise<AgentSkillImportPreview>;

Example:

import { agent } from "./client.ts";

const preview = await agent.skills.previewImport({
  repoUrl: "https://github.com/OWNER/REPO",
  subpath: "skills/photo-editing",
});
console.log(preview);

Guide: skills. Types: AgentSkillSource, AgentResourceOptions, AgentSkillImportPreview.

skills.retrieve

Read a visible fal or installed skill by ID.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentSkill>;

Example:

import { agent } from "./client.ts";

const skill =
  await agent.skills.retrieve("SKILL_ID");
console.log(skill.body);

Guide: skills. Types: AgentResourceOptions, AgentSkill.

skills.save

Replace custom skill content. Saving an imported skill detaches its GitHub source and disables source updates.

Signature

(
  id: string,
  content: AgentSkillContent,
  options?: AgentResourceOptions,
) =>
  Promise<{
    skill: AgentInstalledSkill;
    presetClash: boolean;
  }>;

Example:

import { agent } from "./client.ts";

await agent.skills.save("SKILL_ID", {
  name: "product-photos",
  description: "Create consistent product photos.",
  body: "Preserve the product shape and colors.",
});

Guide: skills. Types: AgentSkillContent, AgentResourceOptions, AgentInstalledSkill.

skills.setEnabled

Enable or disable one skill. Pass its origin and ID from skills.list. The account-level skills switch still applies.

Signature

(
  input: {
    origin: "fal" | "user";
    key: string;
    enabled: boolean;
  },
  options?: AgentResourceOptions,
) => Promise<{ ok: true }>;

Example:

import { agent } from "./client.ts";

await agent.skills.setEnabled({
  origin: "user",
  key: "SKILL_ID",
  enabled: true,
});

Guide: skills. Types: AgentResourceOptions.

skills.uninstall

Remove an installed user skill and its disabled preference entry. Fal skills cannot be uninstalled.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<{ ok: true }>;

Example:

import { agent } from "./client.ts";

await agent.skills.uninstall("SKILL_ID");

Guide: skills. Types: AgentResourceOptions.

skills.update

Update an imported skill from its repository default branch. Replaces its body, references, assets, and source commit.

Signature

(id: string, options?: AgentResourceOptions) =>
  Promise<AgentInstalledSkill>;

Example:

import { agent } from "./client.ts";

const skill = await agent.skills.update("SKILL_ID");
console.log(skill.sourceCommitSha);

Guide: skills. Types: AgentResourceOptions, AgentInstalledSkill.

⌘I

​Responses

​responses.answer

​responses.cancel

​responses.create

​responses.retrieve

​responses.selectFinalArtifacts

​responses.stream

​responses.wait

​run

​stream

​Conversations

​conversations.create

​conversations.delete

​conversations.fork

​conversations.generationSummary

​conversations.items.list

​conversations.list

​conversations.retrieve

​conversations.sharing.retrieve

​conversations.sharing.update

​conversations.update

​Plans

​plans.retrieve

​plans.run

​plans.update

​Artifacts

​artifacts.retrieve

​Projects

​projects.assets.attach

​projects.assets.detach

​projects.collections.attach

​projects.collections.detach

​projects.conversations.add

​projects.conversations.create

​projects.conversations.list

​projects.conversations.remove

​projects.conversations.setMemoryPrivacy

​projects.create

​projects.delete

​projects.documents.attach

​projects.documents.import

​projects.documents.list

​projects.documents.preview

​projects.documents.remove

​projects.documents.retry

​projects.documents.upload

​projects.list

​projects.memory.create

​projects.memory.retrieve

​projects.memory.update

​projects.resources

​projects.retrieve

​projects.update

​Models

​models.capabilities

​models.list

​models.listAgentModels

​Settings

​settings.conversations.retrieve

​settings.conversations.update

​settings.defaults.retrieve

​settings.defaults.update

​settings.projects.retrieve

​settings.projects.update

​Preferences

​preferences.retrieve

​preferences.update

​Queue

​queue.cancel

​queue.dispatch

​queue.edit

​queue.reorder

​queue.retrieve

​queue.run

​queue.setApproval

​queue.setHalted

​Runs

​runs.answer

​runs.cancel

​runs.retrieve

Responses

responses.answer

responses.cancel

responses.create

responses.retrieve

responses.selectFinalArtifacts

responses.stream

responses.wait

run

stream

Conversations

conversations.create

conversations.delete

conversations.fork

conversations.generationSummary

conversations.items.list

conversations.list

conversations.retrieve

conversations.sharing.retrieve

conversations.sharing.update

conversations.update

Plans

plans.retrieve

plans.run

plans.update

Artifacts

artifacts.retrieve

Projects

projects.assets.attach

projects.assets.detach

projects.collections.attach

projects.collections.detach

projects.conversations.add

projects.conversations.create

projects.conversations.list

projects.conversations.remove

projects.conversations.setMemoryPrivacy

projects.create

projects.delete

projects.documents.attach

projects.documents.import

projects.documents.list

projects.documents.preview

projects.documents.remove

projects.documents.retry

projects.documents.upload

projects.list

projects.memory.create

projects.memory.retrieve

projects.memory.update

projects.resources

projects.retrieve

projects.update

Models

models.capabilities

models.list

models.listAgentModels

Settings

settings.conversations.retrieve

settings.conversations.update

settings.defaults.retrieve

settings.defaults.update

settings.projects.retrieve

settings.projects.update

Preferences

preferences.retrieve

preferences.update

Queue

queue.cancel

queue.dispatch

queue.edit

queue.reorder

queue.retrieve

queue.run

queue.setApproval

queue.setHalted

Runs

runs.answer

runs.cancel

runs.retrieve