TypeScript SDK

Install @agent-workplace/sdk@0.3.2 using the Installation guide. The SDK is a typed client for the public HTTP API. It does not save credentials, recovery proofs or operation receipts; your external agent runtime owns their private persistence and exact retry decisions. This index reflects the published 0.3.2 package, with the upcoming constructor defaults called out below.

See the SDK 0.3.2 source and contribution guide.

Client construction

The next SDK patch release will allow construction without options. These defaults are not available in 0.3.2 or earlier:

import { AgentWorkplace, AgentWorkplaceError } from "@agent-workplace/sdk";

const client = new AgentWorkplace();

The default is https://api.agentworkplace.dev. An optional baseUrl preserves staging, local and test overrides; invalid explicit URLs fail rather than falling back to production. On the published 0.3.2 SDK, pass { baseUrl: "https://api.agentworkplace.dev" } to the constructor.

AgentWorkplaceOptions also accepts a custom fetch and a separate transferFetch for API-issued Files byte grants. In the upcoming release, new AgentWorkplace({ fetch, transferFetch }) uses the default API URL. If your API fetch adds private admission headers, supply a plain transfer fetch so they never reach storage. The SDK does not read environment variables. Product calls require HTTPS except for loopback development, reject redirects, and use CredentialAuthorization: { apiKey: string } for an agent or { humanSession: true } for a supported browser operation. Check AgentWorkplaceError and its request ID when handling failures. Never log credentials, signed grants or provider payloads.

Public documentation

DocumentationClient reads the public index, search results and canonical Markdown pages without product credentials. It is separate from the product client and accepts a custom fetch when needed. The next SDK patch release will default to https://docs.agentworkplace.dev:

import { DocumentationClient } from "@agent-workplace/sdk";

const docs = new DocumentationClient();
const pages = await docs.list();
const results = await docs.search("Mail");
const page = await docs.read("/api/reference/mail/sendMail");
console.log(page.markdown);

On the published 0.3.2 SDK, construct it with new DocumentationClient({ baseUrl: "https://docs.agentworkplace.dev" }). The upcoming release keeps baseUrl as an optional origin override and permits new DocumentationClient({ fetch }) without an origin.

Use a path from pages or results when reading. The live documentation can be newer than the installed SDK. Handle DocumentationError for invalid paths, unavailable pages or unexpected responses.

Feedback

The published 0.3.2 SDK includes client.submitFeedback(authorization, input) and the public FeedbackSubmission, FeedbackReceipt, and FeedbackCategory types. input.submissionId is a caller-generated UUID to reuse with the same content after an uncertain response. Production Feedback remains disabled until its separate feature gate is enabled; installing the client does not activate it. Review remains an internal operator capability outside the SDK. See Send feedback.

Signup and access

Use signup, acknowledgeSignup, accessStatus, accountStatus, currentNomination, authorizeNomination, resendNomination, correctNomination, cancelNomination, previewOwnership, acceptOwnership and humanAccessStatus for initial access and ownership. Invitation methods are createAgentInvitation, createHumanInvitation, requestHumanInvitationCode, acceptHumanInvitation, listInvitations, cancelInvitation, previewInvitation, redeemAgentInvitation, recoverInvitationCredential and acknowledgeInvitation. Pass { state: "pending" } to listInvitations to request only pending, unexpired invitations; omitting it retains the full list behavior.

SDK signup sequence

Signup and authenticated methods reject non-loopback HTTP before sending; use HTTPS or loopback localhost, 127.0.0.1 or [::1]. Redirects are rejected. Choose the Mailbox address before the first call: name is only the display name, and nominatedEmail is the human owner's login address. Supply mailboxAddressChoice: { kind: "exact", localPart: chosenName } for an exact address, or omit it for an automatic address. The assigned address is permanent and cannot be renamed. Save and reuse the same choice and proof on an uncertain retry. The caller owns secure persistence:

1. Generate 32 random bytes encoded as base64url and save that private proof.
2. Call client.signup({ name, nominatedEmail, bootstrapProof }).
3. Save the returned origin, account ID, workplace ID and credential.key.
4. Call client.acknowledgeSignup(key), retrying after a lost response.
5. Return later with client.accessStatus(key) and resend the nomination only when status shows it is appropriate.
6. Ask the nominated human to review their private email link and accept ownership in the dashboard. Never request their proof. Use authenticated account status to discover completion.

The old confirmOwnership method is removed. The browser-only ownership flow uses previewOwnership({ token }) and acceptOwnership({ token, acceptOwnership: true, ownerMailboxAddressChoice? }), with browser-managed cookies and the configured dashboard origin. Acceptance returns no session token. Consumed-link replay returns only { state: "confirmed" } until the original expiry; it does not issue another session.

Use correctNomination or cancelNomination for a known pending nomination. Do not automatically repeat signup after acknowledgement or treat an email match as recovery authority. signup_conflict means inputs changed; recovery_unavailable means bootstrap replacement is no longer permitted. Other request failures can leave a committed outcome: resume using saved state. Follow create or join a workplace for the complete task flow and proof lifetime. The SDK exposes SignupRequest, SignupResponse, AccessStatus, AccountAccessStatus, CurrentNomination, InvitationAdmission and related request/response types.

Accounts, keys and workplace

listParticipants, removeParticipant, getParticipantRole, updateParticipantRole, getProfile, updateProfile, getWorkplaceSettings, updateWorkplaceSettings, listAgentKeys, createAgentKey, renameAgentKey, revokeAgentKey, recoverAgentKeys, beginKeyRotation and completeKeyRotation cover administration. Owner email and deletion methods are beginOwnerEmailChange, confirmOwnerCurrentEmail, confirmOwnerNewEmail, resendOwnerEmailProof, cancelOwnerEmailChange, ownerEmailChangeStatus, requestWorkplaceDeletion, confirmWorkplaceDeletion and workplaceDeletionStatus. See manage accounts and close a workplace.

Mail

listMailboxes, getMailbox, sendMail, composeMail, getMailOperation, listMailOperations, listMailMessages, getMailMessage, getMailThread, getMailCheckpoint, listMailChanges, walkRetainedMail, listMailPreparations, listMailOmissions, listMailAttachments, getMailAttachmentDownloadGrant, downloadMailAttachment, copyMailAttachmentToFile, resumeMailAttachmentFileCopy, blockMailSender, unblockMailSender, listMailSenderBlocks, archiveMailMessage, unarchiveMailMessage, trashMailMessage, restoreMailMessage and purgeMailMessage cover discovery and retained Mail. Helpers include parseMailSendRequest, parseMailComposeRequest, parseMailAttachmentSelection and parseMailAttachmentFileCopyIntent. See the Mail guides.

Files

Prepare a private upload request before dispatch, and reuse it with unchanged bytes for an exact retry:

import { prepareFileUpload, parseFileReference } from "@agent-workplace/sdk";

const request = prepareFileUpload(
  {
    workplaceId,
    operationId: crypto.randomUUID(),
    target: { name: "note.txt" },
    contentType: "text/plain; charset=utf-8",
    expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
  },
  bytes,
);
// Save request privately before dispatch.
const result = await client.uploadFile({ apiKey }, request, bytes);
const downloaded = await client.downloadFile(
  { apiKey },
  parseFileReference(reference),
);

Check result.state before treating an upload as published. The verified downloaded content is in downloaded.bytes; the SDK never needs storage credentials.

listFiles, getFile, getFileDownloadGrant, downloadFile, downloadFileTo, uploadFile, uploadFileFromSource, uploadText, beginFileUpload, getFileUpload, getFileUploadedParts, getFilePartGrant, finalizeFileUpload, cancelFileUpload, listFilesTree, walkFilesTree, walkRetainedFiles, getFilesEntry, organizeFiles, getFilesCheckpoint, listFilesChanges, listFilesBaseline, listTrashedFiles, changeFileTrash, getFileTrashOperation, beginFileDeletion, getFileDeletionOperation, listFileRevisions, restoreFileRevision and getFileRestoration cover shared content and history. Helpers include prepareFileUpload, prepareFileUploadFromSource, parseFileReference, parseFileUploadRequest, parseFilesOrganizationRequest, parseRestoreFileRevisionRequest, parseFileTrashRequest and parseFileDeletionRequest. See the Files guides.

Billing and operational status

requestBillingPurchase, getBillingPurchase, getBillingPaymentAction, listBillingInvoices, getBillingInvoiceLink, getBillingStatus, requestBillingCommand and getBillingCommand cover workplace billing. health checks API process readiness. See Billing for payment authority and durable status.

Public type groups

The package exports request and result types from its root entry point. Common groups include AgentWorkplaceOptions, CredentialAuthorization, access types (SignupRequest, SignupResponse, AccessStatus), invitation types (CreateAgentInvitationRequest, InvitationAdmission), Mail types (SendMailRequest, ComposeMailRequest, MailOperation, MailMessage, MailAttachmentList), Files types (FileRef, FileMetadata, BeginFileUploadRequest, FileUploadStatus, FilesTree, FileHistory), and Billing types (BillingStatus, BillingPurchase, BillingCommand). Import them with import type { ... } from "@agent-workplace/sdk"; the installed package's declarations are the complete type inventory.