@onehorizon/sdk-js

v5.5.0

Published

10 days ago

Node.js and JavaScript SDK for One Horizon

0High
0Medium
0Low

tijnvdaelen

geeza

@onehorizon/sdk-js

JavaScript SDK for the One Horizon API. It is generated from the public OpenAPI spec, so the clients and TypeScript models follow the API contract. Use it from Node.js or a browser app to work with tasks, comments, documents, teams, users, API keys, and taxonomy labels.

Environments
- Node.js
- Webpack
- Browserify
Language levels
- ES5 - you must have a Promises/A+ library installed
- ES6
Module systems
- CommonJS
- ES6 module system

Install

npm install @onehorizon/sdk-js

yarn add @onehorizon/sdk-js

pnpm add @onehorizon/sdk-js

Quick Start

import { Configuration, LabelType, TaskPriority, TasksApi } from '@onehorizon/sdk-js'

const config = new Configuration({
  accessToken: process.env.ONE_API_KEY
})

const tasks = new TasksApi(config)

const bug = await tasks.reportBug({
  workspaceId: 'current',
  report: { title: 'Checkout fails after applying a discount' }
})

const idea = await tasks.submitIdea({
  workspaceId: 'current',
  report: {
    title: 'Let customers save multiple shipping addresses',
    description: 'Customers want to reuse addresses during checkout.',
    reporterUserId: 'u_...',
    source: 'customer-portal',
    priority: TaskPriority.Medium,
    teamIds: new Set(['team_...']),
    assigneeIds: new Set(['u_...']),
    labels: [{ name: 'Checkout', type: LabelType.Component }]
  }
})

reportBug and submitIdea create Triage items with server-owned defaults. Use createTask when you need direct control over the underlying task model.

Authentication

Set Configuration.accessToken to a One Horizon bearer token:

API key - use this for backend integrations, scheduled jobs, and CI. Create one in your dashboard.
OAuth access token - use this for CLI and MCP flows.

The SDK sends the value as Authorization: Bearer <token>.

For workspace-scoped requests, pass workspaceId: 'current'. The API resolves it from the token, so your integration does not need to store a workspace ID.

If you use OAuth access tokens, refresh them before they expire. An async resolver works too:

const config = new Configuration({
  accessToken: async () => await getAccessToken()
})

Reference

AgentsApi

acknowledgeAgentWorkerControlSignal

acknowledgeAgentWorkerControlSignal(workspaceId, agentId, workerId, request)

Acknowledge worker control signal

Acknowledges a pending worker control signal. Stale acknowledgements do not clear newer signals.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the worker.
  agentId: "agentId_example",
  // string | Worker acknowledging the signal.
  workerId: "workerId_example",
  // AgentWorkerControlSignalAckRequest
  request: ...,
}

const data = await agentsApi.acknowledgeAgentWorkerControlSignal(params);

Parameters

Return type

AgentWorkerResponse

cancelAgentSession

cancelAgentSession(workspaceId, agentId, sessionId, update)

Cancel agent session

Cancels a visible queued, pending, active, awaiting-input, or stale agent session. Local sessions can only be cancelled by the local owner. If the session has an active claim, the claim is released as part of cancellation.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the session.
  agentId: "agentId_example",
  // string | Session to cancel.
  sessionId: "sessionId_example",
  // AgentSessionCancelRequest (optional)
  update: ...,
}

const data = await agentsApi.cancelAgentSession(params);

Parameters

Return type

AgentSession

claimAgentSession

claimAgentSession(workspaceId, agentId, workerId, sessionId, claim)

Claim agent session

Leases a queued session to this worker before execution starts. Claiming is the concurrency boundary: if another worker already holds an active claim, this request is rejected.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent the worker runs.
  agentId: "agentId_example",
  // string | Worker requesting the lease.
  workerId: "workerId_example",
  // string | Queued session to claim.
  sessionId: "sessionId_example",
  // AgentClaimRequest (optional)
  claim: ...,
}

const data = await agentsApi.claimAgentSession(params);

Parameters

Return type

AgentClaimResponse

completeAgentSession

completeAgentSession(workspaceId, agentId, workerId, sessionId, update)

Complete agent session

Marks a claimed session complete and closes the active claim. The `claimId` must match the worker's active claim.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the session.
  agentId: "agentId_example",
  // string | Worker holding the active claim.
  workerId: "workerId_example",
  // string | Session to complete.
  sessionId: "sessionId_example",
  // AgentSessionUpdate
  update: ...,
}

const data = await agentsApi.completeAgentSession(params);

Parameters

Return type

AgentSession

createAgentActivity

createAgentActivity(workspaceId, agentId, workerId, sessionId, activity)

Create agent activity

Records progress, plan changes, external links, completion notes, failures, or policy decisions for a claimed session. The worker and claim in the body must match the active claim.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the session.
  agentId: "agentId_example",
  // string | Worker creating the activity.
  workerId: "workerId_example",
  // string | Session receiving the activity.
  sessionId: "sessionId_example",
  // AgentActivity
  activity: ...,
}

const data = await agentsApi.createAgentActivity(params);

Parameters

Return type

AgentActivityResponse

createAgentWorker

createAgentWorker(workspaceId, agentId, worker)

Registers or updates one execution runtime for an agent. Local workers are private to the authenticated user.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent this worker can execute.
  agentId: "agentId_example",
  // AgentWorker
  worker: ...,
}

const data = await agentsApi.createAgentWorker(params);

Parameters

Return type

AgentWorkerResponse

deferAgentSessionClaim

deferAgentSessionClaim(workspaceId, agentId, workerId, sessionId, request)

Defer agent session claim

Records that a worker found a claimable session but deferred claiming it because of local resource backpressure. Does not require an active claim.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the session.
  agentId: "agentId_example",
  // string | Worker deferring the claim.
  workerId: "workerId_example",
  // string | Session that could not be claimed yet.
  sessionId: "sessionId_example",
  // DeferAgentSessionClaimRequest
  request: ...,
}

const data = await agentsApi.deferAgentSessionClaim(params);

Parameters

Return type

DeferAgentSessionClaimResponse

discoverCapabilitySource

discoverCapabilitySource(workspaceId, sourceRequest)

Discover capabilities in a repository

Resolves a Git repository and returns its supported Agent Skills or MCP servers without storing artifacts or changing the workspace catalog. A two-segment skills.sh collection URL is resolved to its backing GitHub repository for Agent Skill discovery.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // CapabilitySourceResolveRequest
  sourceRequest: ...,
}

const data = await agentsApi.discoverCapabilitySource(params);

Parameters

Return type

CapabilitySourceDiscovery

downloadRuntimeArtifact

downloadRuntimeArtifact(workspaceId, artifactId)

Download a verified third-party runtime artifact

Returns the inert portable bundle selected by a source-specific resolver. The artifact is workspace-scoped, bearer-authenticated, and digest-checked before delivery. Candidate code is not executed by this endpoint.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  artifactId: "artifactId_example",
}

const data = await agentsApi.downloadRuntimeArtifact(params);

Parameters

Return type

Blob

failAgentSession

failAgentSession(workspaceId, agentId, workerId, sessionId, update)

Fail agent session

Marks a claimed session as failed and closes the active claim. Use this when the worker cannot continue or the model run ends with an unrecoverable error.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the session.
  agentId: "agentId_example",
  // string | Worker holding the active claim.
  workerId: "workerId_example",
  // string | Session to fail.
  sessionId: "sessionId_example",
  // AgentSessionUpdate
  update: ...,
}

const data = await agentsApi.failAgentSession(params);

Parameters

Return type

AgentSession

fetchAgentSession

fetchAgentSession(workspaceId, agentId, sessionId)

Fetch agent session

Fetches one visible agent work session. Local sessions are only visible to the owning user.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the session.
  agentId: "agentId_example",
  // string | Session to retrieve.
  sessionId: "sessionId_example",
}

const data = await agentsApi.fetchAgentSession(params);

Parameters

Return type

AgentSession

fetchAgentWorker

fetchAgentWorker(workspaceId, agentId, workerId)

Fetch agent worker

Fetches one worker. Local workers are only visible to their owner.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the worker.
  agentId: "agentId_example",
  // string | Worker to retrieve.
  workerId: "workerId_example",
}

const data = await agentsApi.fetchAgentWorker(params);

Parameters

Return type

AgentWorker

fetchCapability

fetchCapability(workspaceId, capabilityId)

Fetch workspace capability

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  capabilityId: "capabilityId_example",
}

const data = await agentsApi.fetchCapability(params);

Parameters

Return type

CapabilityCatalogEntry

getRuntimePolicy

getRuntimePolicy(workspaceId)

Fetch local runtime policy

Returns the current versioned runtime eligibility policy for authenticated local workers. Workers cache it until expiresAt and fail closed when no current policy is available.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
}

const data = await agentsApi.getRuntimePolicy(params);

Parameters

Return type

RuntimePolicyBundle

getRuntimePublisherPolicy

getRuntimePublisherPolicy(workspaceId, policyId)

Fetch a runtime publisher identity policy

Returns server-owned publisher authorization independently from source resolution.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  policyId: "policyId_example",
}

const data = await agentsApi.getRuntimePublisherPolicy(params);

Parameters

Return type

RuntimePublisherPolicy

getRuntimeVerifiedRelease

getRuntimeVerifiedRelease(workspaceId, releaseId)

Fetch runtime verified-release evidence

Returns a release statement and Sigstore bundle bound to a separately managed publisher policy.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  releaseId: "releaseId_example",
}

const data = await agentsApi.getRuntimeVerifiedRelease(params);

Parameters

Return type

RuntimeVerifiedRelease

heartbeatAgentWorker

heartbeatAgentWorker(workspaceId, agentId, workerId, request)

Heartbeat agent worker

Marks a worker online and refreshes its heartbeat timestamp. Heartbeats do not create work or extend active claims. Use the session claim endpoint for claim leases.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the worker.
  agentId: "agentId_example",
  // string | Worker sending the heartbeat.
  workerId: "workerId_example",
  // AgentWorkerHeartbeatRequest (optional)
  request: ...,
}

const data = await agentsApi.heartbeatAgentWorker(params);

Parameters

Return type

AgentWorkerHeartbeatResponse

importCapabilitySource

importCapabilitySource(workspaceId, importRequest)

Resolve selected repository Agent Skills

Resolves and stores verified artifacts for selected skills from one repository archive. This endpoint does not add capabilities to the workspace catalog.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // CapabilitySourceImportRequest
  importRequest: ...,
}

const data = await agentsApi.importCapabilitySource(params);

Parameters

Return type

CapabilitySourceImport

listAgentActivities

listAgentActivities(workspaceId, agentId, workerId, sessionId, page, limit)

List agent activities

Lists progress and audit events recorded for one agent session.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the session.
  agentId: "agentId_example",
  // string | Worker associated with the session view.
  workerId: "workerId_example",
  // string | Session whose activities should be listed.
  sessionId: "sessionId_example",
  // number | Zero-based page index. (optional)
  page: 0,
  // number | Number of items per page. Defaults to 50 and is capped at 100. (optional)
  limit: 50,
}

const data = await agentsApi.listAgentActivities(params);

Parameters

Return type

ListAgentActivitiesResponse

listAgentSessions

listAgentSessions(workspaceId, agentId, status, executionMode, ownerUserId, taskId, workflowRunId, page, limit)

List agent sessions

Lists visible work sessions for one agent. Local sessions are visible only to the local worker owner.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent whose sessions should be listed.
  agentId: "agentId_example",
  // Array<AgentSessionStatus> | Filter by one or more session lifecycle states. (optional)
  status: ...,
  // AgentExecutionMode | Limit results to local or cloud execution sessions. (optional)
  executionMode: ...,
  // string | Filter local sessions by owner. Local sessions are owner-only. (optional)
  ownerUserId: "ownerUserId_example",
  // string | Filter sessions attached to this task or initiative. (optional)
  taskId: "taskId_example",
  // string | Filter sessions attached to this workflow run. (optional)
  workflowRunId: "workflowRunId_example",
  // number | Zero-based page index. (optional)
  page: 0,
  // number | Number of items per page. Defaults to 50 and is capped at 100. (optional)
  limit: 50,
}

const data = await agentsApi.listAgentSessions(params);

Parameters

| Name | Type | Description | Notes | |------------- | ------------- | ------------- | -------------| | workspaceId | string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`. | [Defaults to undefined] | | agentId | string | Agent whose sessions should be listed. | [Defaults to undefined] | | status | Array<AgentSessionStatus> | Filter by one or more session lifecycle states. | [Optional] | | executionMode | AgentExecutionMode | Limit results to local or cloud execution sessions. | [Optional] [Defaults to undefined] [Enum: local, cloud] | | ownerUserId | string | Filter local sessions by owner. Local sessions are owner-only. | [Optional] [Defaults to undefined] | | taskId | string | Filter sessions attached to this task or initiative. | [Optional] [Defaults to undefined] | | workflowRunId | string | Filter sessions attached to this workflow run. | [Optional] [Defaults to undefined] | | page | number | Zero-based page index. | [Optional] [Defaults to 0] | | limit | number | Number of items per page. Defaults to 50 and is capped at 100. | [Optional] [Defaults to 50] |

Return type

ListAgentSessionsResponse

listAgentWorkers

listAgentWorkers(workspaceId, agentId, executionMode, ownerUserId, page, limit)

List agent workers

Lists workers registered for an agent. Local workers are only returned to their owning user; cloud workers can be listed by permitted workspace users.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent whose workers should be listed.
  agentId: "agentId_example",
  // AgentExecutionMode | Limit results to local or cloud workers. (optional)
  executionMode: ...,
  // string | Filter local workers by owner. Local workers are visible only to their owner. (optional)
  ownerUserId: "ownerUserId_example",
  // number | Zero-based page index. (optional)
  page: 0,
  // number | Number of items per page. Defaults to 50 and is capped at 100. (optional)
  limit: 50,
}

const data = await agentsApi.listAgentWorkers(params);

Parameters

| Name | Type | Description | Notes | |------------- | ------------- | ------------- | -------------| | workspaceId | string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`. | [Defaults to undefined] | | agentId | string | Agent whose workers should be listed. | [Defaults to undefined] | | executionMode | AgentExecutionMode | Limit results to local or cloud workers. | [Optional] [Defaults to undefined] [Enum: local, cloud] | | ownerUserId | string | Filter local workers by owner. Local workers are visible only to their owner. | [Optional] [Defaults to undefined] | | page | number | Zero-based page index. | [Optional] [Defaults to 0] | | limit | number | Number of items per page. Defaults to 50 and is capped at 100. | [Optional] [Defaults to 50] |

Return type

ListAgentWorkersResponse

listCapabilities

listCapabilities(workspaceId)

List workspace capabilities

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
}

const data = await agentsApi.listCapabilities(params);

Parameters

Return type

ListCapabilitiesResponse

patchAgentSession

patchAgentSession(workspaceId, agentId, workerId, sessionId, update)

Update claimed agent session

Updates metadata or lifecycle state for a session currently claimed by the worker. The `claimId` must match the active claim. Use this for plan, external URL, or awaiting-input updates while execution is in progress.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the session.
  agentId: "agentId_example",
  // string | Worker holding the active claim.
  workerId: "workerId_example",
  // string | Session to update.
  sessionId: "sessionId_example",
  // AgentSessionUpdate
  update: ...,
}

const data = await agentsApi.patchAgentSession(params);

Parameters

Return type

AgentSession

pollAgentWorkerSessions

pollAgentWorkerSessions(workspaceId, agentId, workerId, page, limit, workerRunId)

Poll sessions visible to worker

Returns queued sessions that this worker is allowed to claim. Local workers only receive sessions created by their owning user; cloud workers receive workspace-visible sessions for their agent.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent the worker runs.
  agentId: "agentId_example",
  // string | Worker asking for claimable sessions.
  workerId: "workerId_example",
  // number | Zero-based page index. (optional)
  page: 0,
  // number | Number of items per page. Defaults to 50 and is capped at 100. (optional)
  limit: 50,
  // string | Active worker run asking for claimable sessions. Runtime or identity precondition failures return 409; other health ineligibility returns an empty list. (optional)
  workerRunId: "workerRunId_example",
}

const data = await agentsApi.pollAgentWorkerSessions(params);

Parameters

| Name | Type | Description | Notes | |------------- | ------------- | ------------- | -------------| | workspaceId | string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`. | [Defaults to undefined] | | agentId | string | Agent the worker runs. | [Defaults to undefined] | | workerId | string | Worker asking for claimable sessions. | [Defaults to undefined] | | page | number | Zero-based page index. | [Optional] [Defaults to 0] | | limit | number | Number of items per page. Defaults to 50 and is capped at 100. | [Optional] [Defaults to 50] | | workerRunId | string | Active worker run asking for claimable sessions. Runtime or identity precondition failures return 409; other health ineligibility returns an empty list. | [Optional] [Defaults to undefined] |

Return type

ListAgentSessionsResponse

releaseAgentSession

releaseAgentSession(workspaceId, agentId, workerId, sessionId, update)

Release agent session

Releases the worker's active claim and puts the session back in the queue. Use this when a worker shuts down or decides it cannot handle the session.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the session.
  agentId: "agentId_example",
  // string | Worker holding the active claim.
  workerId: "workerId_example",
  // string | Session to release.
  sessionId: "sessionId_example",
  // AgentSessionUpdate
  update: ...,
}

const data = await agentsApi.releaseAgentSession(params);

Parameters

Return type

AgentClaimResponse

reportCapabilityCredentialHealth

reportCapabilityCredentialHealth(workspaceId, agentId, workerId, sessionId, report)

Report managed capability credential health

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  agentId: "agentId_example",
  // string
  workerId: "workerId_example",
  // string
  sessionId: "sessionId_example",
  // ReportCapabilityCredentialHealthRequest
  report: ...,
}

const data = await agentsApi.reportCapabilityCredentialHealth(params);

Parameters

Return type

void (Empty response body)

reportCapabilityInspection

reportCapabilityInspection(workspaceId, agentId, workerId, sessionId, report)

Report MCP capability inspection

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  agentId: "agentId_example",
  // string
  workerId: "workerId_example",
  // string
  sessionId: "sessionId_example",
  // ReportCapabilityInspectionRequest
  report: ...,
}

const data = await agentsApi.reportCapabilityInspection(params);

Parameters

Return type

void (Empty response body)

requestAgentWorkerControlSignal

requestAgentWorkerControlSignal(workspaceId, agentId, workerId, request)

Request worker control signal

Requests a stop, pause, resume, or restart signal for a worker. Local worker signals are owner-only.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the worker.
  agentId: "agentId_example",
  // string | Worker to signal.
  workerId: "workerId_example",
  // AgentWorkerControlSignalRequest
  request: ...,
}

const data = await agentsApi.requestAgentWorkerControlSignal(params);

Parameters

Return type

AgentWorkerResponse

resolveCapabilitySource

resolveCapabilitySource(workspaceId, sourceRequest)

Resolve a workspace capability source

Resolves and validates a mutable Agent Skill, MCP server, or plugin source into control-plane-owned immutable provenance. Private git sources use the workspace's provider integration and credentials never leave the server.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // CapabilitySourceResolveRequest
  sourceRequest: ...,
}

const data = await agentsApi.resolveCapabilitySource(params);

Parameters

Return type

CapabilitySourceResolution

resolveRuntimeSource

resolveRuntimeSource(workspaceId, source, kind)

Resolve a third-party runtime source

Resolves a source-specific mutable runtime reference to control-plane-owned immutable provenance. The response never contains publisher authorization policy.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  source: "source_example",
  // 'git' | 'npm' | 'pypi' | 'registry' | 'acp_registry'
  kind: "kind_example",
}

const data = await agentsApi.resolveRuntimeSource(params);

Parameters

Return type

RuntimeSourceResolution

resumeAgentSession

resumeAgentSession(workspaceId, agentId, sessionId, request)

Resume awaiting-input agent session

Queues user input for an awaiting-input session while preserving the active worker claim. The owning worker consumes the input on its next poll.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the session.
  agentId: "agentId_example",
  // string | Session to resume.
  sessionId: "sessionId_example",
  // AgentSessionResumeRequest
  request: ...,
}

const data = await agentsApi.resumeAgentSession(params);

Parameters

Return type

AgentSession

resumeAgentWorker

resumeAgentWorker(workspaceId, agentId, workerId)

Resume a paused worker

Clears the provider usage-limit cooldown on a worker that is paused, so it can take work again without waiting for the cooldown to elapse. No usage check is performed: if the next attempt hits the limit again the worker returns to paused. Resuming a worker that is not paused succeeds and leaves its status unchanged. Local worker resumes are owner-only.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the worker.
  agentId: "agentId_example",
  // string | Worker to resume.
  workerId: "workerId_example",
}

const data = await agentsApi.resumeAgentWorker(params);

Parameters

Return type

AgentWorkerResponse

sealAgentSessionCapabilities

sealAgentSessionCapabilities(workspaceId, agentId, workerId, sessionId, report)

Seal agent session capabilities

Seals the immutable capability manifest after repository and local discovery. Requires the active session claim.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  agentId: "agentId_example",
  // string
  workerId: "workerId_example",
  // string
  sessionId: "sessionId_example",
  // SealAgentSessionCapabilitiesRequest
  report: ...,
}

const data = await agentsApi.sealAgentSessionCapabilities(params);

Parameters

Return type

SealAgentSessionCapabilitiesResponse

updateAgentWorker

updateAgentWorker(workspaceId, agentId, workerId, worker)

Update agent worker

Updates worker metadata, availability, or trusted policy summary. Local workers can only be updated by the owning user.

Example

...

const agentsApi = new AgentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Agent that owns the worker.
  agentId: "agentId_example",
  // string | Worker to update.
  workerId: "workerId_example",
  // AgentWorker
  worker: ...,
}

const data = await agentsApi.updateAgentWorker(params);

Parameters

Return type

AgentWorker

ApiKeysApi

createApiKey

createApiKey(workspaceId, apiKey)

Create API key

Creates a new workspace API key. Requires a workspace owner or admin OAuth token. The secret is returned once at creation time and cannot be retrieved again. Store it immediately in a secrets manager or environment variable (`ONE_API_KEY`).

Example

...

const apiKeysApi = new ApiKeysApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // CreateApiKeyRequest
  apiKey: ...,
}

const data = await apiKeysApi.createApiKey(params);

Parameters

Return type

CreateApiKeyResponse

listApiKeys

listApiKeys(workspaceId)

List API keys

Lists workspace API keys. Returns safe metadata only; secret values are never returned after creation. Requires a workspace owner or admin OAuth token; API keys cannot call API key management endpoints.

Example

...

const apiKeysApi = new ApiKeysApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
}

const data = await apiKeysApi.listApiKeys(params);

Parameters

Return type

ListApiKeysResponse

revokeApiKey

revokeApiKey(workspaceId, keyId)

Revoke API key

Permanently revokes a workspace API key. Requires a workspace owner or admin OAuth token. Revocation is immediate. Any in-flight requests using the key will be rejected.

Example

...

const apiKeysApi = new ApiKeysApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  keyId: "keyId_example",
}

const data = await apiKeysApi.revokeApiKey(params);

Parameters

Return type

void (Empty response body)

AuthApi

getUser

getUser()

Get authenticated user

Returns the user identity behind an OAuth token. Use this to verify that an OAuth credential is valid and to retrieve the user's ID before making workspace-scoped calls. Not available for API keys.

Example

...

const authApi = new AuthApi(cfg);


const data = await authApi.getUser();

Parameters

This endpoint does not need any parameter.

Return type

AuthUser

CommentsApi

deleteTaskComment

deleteTaskComment(workspaceId, taskId, commentId)

Delete comment

Deletes a task comment by ID. Comments with existing replies may be tombstoned rather than removed immediately to preserve thread context.

Example

...

const commentsApi = new CommentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Task or initiative that owns the comment.
  taskId: "taskId_example",
  // string | Comment to delete.
  commentId: "commentId_example",
}

const data = await commentsApi.deleteTaskComment(params);

Parameters

Return type

void (Empty response body)

listTaskComments

listTaskComments(workspaceId, taskId, parentCommentId)

List task comments

Lists the full comment thread for a task. Pass `parentCommentId` to fetch replies for a specific top-level comment only.

Example

...

const commentsApi = new CommentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Task or initiative whose comments should be listed.
  taskId: "taskId_example",
  // string | Return replies for this parent comment only. (optional)
  parentCommentId: "parentCommentId_example",
}

const data = await commentsApi.listTaskComments(params);

Parameters

Return type

ListTaskCommentsResponse

saveTaskComment

saveTaskComment(workspaceId, taskId, taskComment)

Create comment

Creates a new comment on a task. Include `parentCommentId` in the request body to post a threaded reply. The workspace and task identifiers are always taken from the URL, even if they are present in the body.

Example

...

const commentsApi = new CommentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Task or initiative to comment on.
  taskId: "taskId_example",
  // TaskCommentSnapshot
  taskComment: ...,
}

const data = await commentsApi.saveTaskComment(params);

Parameters

Return type

TaskComment

toggleTaskCommentReaction

toggleTaskCommentReaction(workspaceId, taskId, commentId, reaction)

Toggle comment reaction

Adds the current user's reaction if it is missing, or removes it if it already exists.

Example

...

const commentsApi = new CommentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Task or initiative that owns the comment.
  taskId: "taskId_example",
  // string | Comment receiving or losing the reaction.
  commentId: "commentId_example",
  // ToggleTaskCommentReactionRequest
  reaction: ...,
}

const data = await commentsApi.toggleTaskCommentReaction(params);

Parameters

Return type

TaskComment

unwatchTask

unwatchTask(workspaceId, taskId)

Unwatch task

Removes the current user from the task watcher list.

Example

...

const commentsApi = new CommentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Task to stop watching.
  taskId: "taskId_example",
}

const data = await commentsApi.unwatchTask(params);

Parameters

Return type

void (Empty response body)

watchTask

watchTask(workspaceId, taskId)

Watch task

Adds the current user as a watcher so they receive updates for the task.

Example

...

const commentsApi = new CommentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Task to watch.
  taskId: "taskId_example",
}

const data = await commentsApi.watchTask(params);

Parameters

Return type

TaskContributor

DocumentsApi

createDocument

createDocument(workspaceId, document)

Create document

Creates a workspace document. To attach it to a task or initiative, send the returned `documentId` to the task-document attachment endpoint. With an API key, pass `workspaceId=current`. The API resolves the workspace from the key.

Example

...

const documentsApi = new DocumentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // DocumentSnapshot
  document: ...,
}

const data = await documentsApi.createDocument(params);

Parameters

Return type

Document

deleteDocument

deleteDocument(workspaceId, documentId)

Delete document

Permanently deletes a workspace document. Task-document and workflow provenance links are removed by the document relation cascade. With an API key, pass `workspaceId=current`. The API resolves the workspace from the key.

Example

...

const documentsApi = new DocumentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Document to delete.
  documentId: "documentId_example",
}

const data = await documentsApi.deleteDocument(params);

Parameters

Return type

void (Empty response body)

fetchDocument

fetchDocument(workspaceId, documentId)

Get document

Fetches one document by ID. This returns the full `content` body when the document has one.

Example

...

const documentsApi = new DocumentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | Document to retrieve.
  documentId: "documentId_example",
}

const data = await documentsApi.fetchDocument(params);

Parameters

Return type

Document

findRelatedBlocks

findRelatedBlocks(workspaceId, workflowRunId, findRelatedBlocksRequest)

Find related workflow blocks

Follow document-block related refs across documents in a workflow run.

Example

...

const documentsApi = new DocumentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  workflowRunId: "workflowRunId_example",
  // FindRelatedBlocksRequest
  findRelatedBlocksRequest: ...,
}

const data = await documentsApi.findRelatedBlocks(params);

Parameters

Return type

FindRelatedBlocksResponse

listDocumentBlocks

listDocumentBlocks(workspaceId, documentId, types, statuses, severities, relatedIds, files)

List document blocks

List addressable document-block:v1 sections from a workflow document without loading full bodies.

Example

...

const documentsApi = new DocumentsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string
  documentId: "documentId_example",
  // Array<string> (optional)
  types: ...,
  // Array<string> (optional)
  statuses: ...,
  // Array<string> (optional)
  severities: ...,
  // Array<string> (optional)
  relatedIds: ...,
  // Array<string> (optional)
  files: ...,
}

const data = await documentsApi.listDocumentBlocks(params);

Parameters

Return type

ListDocumentBlocksResponse

listDocuments

listDocuments(workspaceId, query, taskId, workflowArtifactType, type, status, createdBy, updatedBy, page, limit, includeContent)

List documents

Finds workspace documents by title or metadata. Pass `taskId` for documents attached to a task or initiative. Pass `workflowArtifactType` with `taskId` to return that task's canonical workflow artifact document. Set `includeContent=false` when IDs, titles, and excerpts are enough. With an API key, pass `workspaceId=current`. The API resolves the workspace from the key.

Example

...

const documentsApi = new DocumentsApi(cfg);

const params = {
  //

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@onehorizon/sdk-js

Links

Install

Quick Start

Authentication

Reference

AgentsApi

acknowledgeAgentWorkerControlSignal

Example

Parameters

Return type

cancelAgentSession

Example

Parameters

Return type

claimAgentSession

Example

Parameters

Return type

completeAgentSession

Example

Parameters

Return type

createAgentActivity

Example

Parameters

Return type

createAgentWorker

Example

Parameters

Return type

deferAgentSessionClaim

Example

Parameters

Return type

discoverCapabilitySource

Example

Parameters

Return type

downloadRuntimeArtifact

Example

Parameters

Return type

failAgentSession

Example

Parameters

Return type

fetchAgentSession

Example

Parameters

Return type

fetchAgentWorker

Example

Parameters

Return type

fetchCapability

Example

Parameters

Return type

getRuntimePolicy

Example

Parameters

Return type

getRuntimePublisherPolicy

Example

Parameters

Return type

getRuntimeVerifiedRelease

Example

Parameters

Return type

heartbeatAgentWorker

Example

Parameters