@onehorizon/sdk-js

v2.11.2

Published

18 hours 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, TasksApi, TaskKind, TaskScope, TaskStatus, TaskContributionType } from '@onehorizon/sdk-js'

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

const tasks = new TasksApi(config)

// Listing all active initiatives
const { tasks: active } = await tasks.listTasks({
  workspaceId: 'current',
  scope: [TaskScope.Initiative],
  status: [
    TaskStatus.Planned, 
    TaskStatus.InProgress, 
    TaskStatus.Review
  ]
})

// Fetch an initiative by ID.
const initiative = await tasks.fetchTask({
  workspaceId: 'current',
  taskId: 'tsk_...'
})

// Creating an initiative
const initiative = await tasks.createTask({
  workspaceId: 'current',
  task: {
    userId: 'u_...', // Owner of the task
    // Assign to user
    contributors: [
      {
        userId: 'u_...',
        type: TaskContributionType.Assignee
      }
    ],
    title: 'Project Jackbox',
    scope: TaskScope.Initiative
  }
})

// Updating an initiative
await tasks.updateTask({
  workspaceId: 'current',
  taskId: 'tsk_...',
  task: {
    ...initiative,
    status: TaskStatus.InProgress,
  }
})

// Reporting a bug.
const bug = await tasks.createTask({
  workspaceId: 'current',
  task: {
    userId: 'u_...',
    title: 'Slack recap sends duplicate updates after timezone change',
    description: 'Teams receive duplicate recap messages after timezone preferences change.',
    kind: TaskKind.Bug,
  }
})

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

createAgent

createAgent(workspaceId, agent)

Create agent

Creates an agent profile backed by an existing OAuth client. This makes the agent available as a capability. A worker must still claim a session before anything executes.

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",
  // AgentProfileRequest
  agent: ...,
}

const data = await agentsApi.createAgent(params);

Parameters

Return type

AgentResponse

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

createAgentSession

createAgentSession(workspaceId, agentId, session)

Create agent session

Queues one visible unit of agent work. Creating a session does not start execution. An eligible worker must claim the session first. For local execution, the authenticated user must be the local 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 should receive the session.
  agentId: "agentId_example",
  // AgentSessionRequest
  session: ...,
}

const data = await agentsApi.createAgentSession(params);

Parameters

Return type

AgentSessionResponse

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

deleteAgentWorker

deleteAgentWorker(workspaceId, agentId, workerId)

Delete agent worker

Deletes a worker registration. Local workers can only be deleted by 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 registration to delete.
  workerId: "workerId_example",
}

const data = await agentsApi.deleteAgentWorker(params);

Parameters

Return type

Status

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

fetchAgent

fetchAgent(workspaceId, agentId)

Fetch agent

Fetches one agent profile and its declared 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",
  // string | Agent profile to retrieve.
  agentId: "agentId_example",
}

const data = await agentsApi.fetchAgent(params);

Parameters

Return type

AgentProfile

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

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

AgentWorkerResponse

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, 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",
  // 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] | | 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

Return type

ListAgentWorkersResponse

listAgents

listAgents(workspaceId, active, page, limit)

List agents

Lists agent profiles available in the workspace. Profiles describe app capabilities, not running processes. Use worker endpoints to inspect execution runtimes.

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",
  // boolean | Return only active or inactive agent profiles. (optional)
  active: true,
  // 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.listAgents(params);

Parameters

Return type

ListAgentsResponse

listWorkspaceAgentSessions

listWorkspaceAgentSessions(workspaceId, agentId, taskId, status, executionMode, ownerUserId, page, limit)

List workspace agent sessions

Lists visible agent work sessions across agents in a workspace. Personal local sessions are only visible to the user who owns the worker they target; cloud sessions follow workspace/app visibility.

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 | Filter to sessions owned by one agent. (optional)
  agentId: "agentId_example",
  // string | Filter sessions attached to this task or initiative. (optional)
  taskId: "taskId_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. In v1, local sessions are owner-only. (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.listWorkspaceAgentSessions(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 | Filter to sessions owned by one agent. | [Optional] [Defaults to undefined] | | taskId | string | Filter sessions attached to this task or initiative. | [Optional] [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. In v1, local sessions are owner-only. | [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

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)

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,
}

const data = await agentsApi.pollAgentWorkerSessions(params);

Parameters

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

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

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

updateAgent

updateAgent(workspaceId, agentId, agent)

Update agent

Updates agent profile metadata, such as display name, active state, or capability labels. Runtime worker state is managed through worker endpoints.

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 profile to update.
  agentId: "agentId_example",
  // AgentProfileRequest
  agent: {"workspaceId":"demo","clientId":"one-cli","name":"Codex","active":false,"capabilities":["code"],"defaultExecutionMode":"local","mentionable":false,"delegatable":false,"cloudEnabled":false},
}

const data = await agentsApi.updateAgent(params);

Parameters

Return type

AgentProfile

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. Use the returned `documentId` as `contentDocumentId` or add it to a task's `documents` array when you want to attach the document to an initiative. 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

fetchDocument

fetchDocument(workspaceId, documentId)

Get document

Fetches one document by ID. Use this when a task's `documentId` references a spec, brief, or design doc and you need the full `content` body.

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

listDocuments

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

List documents

Finds workspace documents by title or metadata. Pass `taskId` to return the documents attached to a task or initiative. Set `includeContent=false` when you only need IDs, titles, and excerpts. 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 | Search document titles. (optional)
  query: "Platformization",
  // string | Filter to documents attached to this task or initiative. (optional)
  taskId: "init-platformization",
  // Array<DocumentType> | Return documents matching one or more document types. (optional)
  type: ["requirement"],
  // Array<DocumentStatus> | Return documents matching one or more workflow statuses. (optional)
  status: ["completed"],
  // string | Return documents created by this user. (optional)
  createdBy: "u6a",
  // string | Return documents last updated by this user. (optional)
  updatedBy: "u6a",
  // number | Zero-based page index. (optional)
  page: 0,
  // number | Number of documents per page. Defaults to 50 and is capped at 200. (optional)
  limit: 20,
  // boolean | Whether to include full document content. Set false for metadata-only list responses that include `excerpt` without the full body. (optional)
  includeContent: false,
}

const data = await documentsApi.listDocuments(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] | | query | string | Search document titles. | [Optional] [Defaults to undefined] | | taskId | string | Filter to documents attached to this task or initiative. | [Optional] [Defaults to undefined] | | type | Array<DocumentType> | Return documents matching one or more document types. | [Optional] | | status | Array<DocumentStatus> | Return documents matching one or more workflow statuses. | [Optional] | | createdBy | string | Return documents created by this user. | [Optional] [Defaults to undefined] | | updatedBy | string | Return documents last updated by this user. | [Optional] [Defaults to undefined] | | page | number | Zero-based page index. | [Optional] [Defaults to 0] | | limit | number | Number of documents per page. Defaults to 50 and is capped at 200. | [Optional] [Defaults to 50] | | includeContent | boolean | Whether to include full document content. Set false for metadata-only list responses that include `excerpt` without the full body. | [Optional] [Defaults to true] |

Return type

ListDocumentsResponse

FilesApi

requestFileUploadUrl

requestFileUploadUrl(workspaceId, file)

Request a file upload URL

Returns a pre-signed S3 PUT URL and required request headers so your server can upload a file directly to private cloud storage. Allowed types: images (`image/*` except `image/svg+xml`) and videos (`video/*`). Maximum size: 100 MB. > Note: The `PUT` request must be sent from a server. Browser clients are blocked by CSP. The `assetUrl` in the response is a proxied URL that requires a valid workspace session. The file is not publicly accessible. Embed it in task descriptions, comments, or document content to reference the file within the platform. Upload the file After receiving the response, perform a `PUT` from your server to `uploadUrl`. Include every key-value pair from the `headers` map: ```bash curl -X PUT <uploadUrl> \ -H "Content-Type: image/png" \ --data-binary "@image.png" ```

Example

...

const filesApi = new FilesApi(cfg);

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

const data = await filesApi.requestFileUploadUrl(params);

Parameters

Return type

FileUploadUrlResponse

LabelsApi

createLabel

createLabel(workspaceId, label)

Create label

Creates a new workspace label definition. The label is not attached to any task. Use `POST /tasks/{taskId}/labels` to create and attach in one step.

Example

...

const labelsApi = new LabelsApi(cfg);

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

const data = await labelsApi.createLabel(params);

Parameters

Return type

Label

deleteLabel

deleteLabel(workspaceId, labelId)

Delete label

Permanently deletes a workspace label definition and all task associations for that label.

Example

...

const labelsApi = new LabelsApi(cfg);

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

const data = await labelsApi.deleteLabel(params);

Parameters

Return type

void (Empty response body)

fetchLabel

fetchLabel(workspaceId, labelId)

Get label

Returns a label definition.

Example

...

const labelsApi = new LabelsApi(cfg);

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

const data = await labelsApi.fetchLabel(params);

Parameters

Return type

Label

listLabels

listLabels(workspaceId, type, page, limit)

List workspace labels

Lists label definitions in the workspace. Use `type` to filter by category.

Example

...

const labelsApi = new LabelsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // LabelType | Return only labels of this type. (optional)
  type: ...,
  // 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 labelsApi.listLabels(params);

Parameters

Return type

ListLabelsResponse

listTaskLabels

listTaskLabels(workspaceId, taskId, type, page, limit)

List task labels

Lists labels on a task. Use `type` to filter by category. Task-specific values are included where set.

Example

...

const labelsApi = new LabelsApi(cfg);

const params = {
  // string | The workspace to operate on. Pass a concrete workspace ID or the reserved value `current`.
  workspaceId: "workspaceId_example",
  // string | ID of the task.
  taskId: "taskId_example",
  // LabelType | Return only labels of this type. (optional)
  type: ...,
  // 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 labelsApi.listTaskLabels(params);

Parameters

Return type

ListTaskLabelsResponse

removeTaskLabel

removeTaskLabel(workspaceId, taskId, labelId)

Remove label from task

Removes a label from a task. The label definition in the workspace is not deleted.

Example

...

const labelsApi = new LabelsApi(cfg);

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

const data = await labelsApi.removeTaskLabel(params);

Parameters

Return type

void (Empty response body)

saveTaskLabel

saveTaskLabel(workspaceId, taskId, label)

Add label to task

Attaches a label to a task. Provide `labelId&#x6

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

createAgent

Example

Parameters

Return type

createAgentActivity

Example

Parameters

Return type

createAgentSession

Example

Parameters

Return type

createAgentWorker

Example

Parameters

Return type

deleteAgentWorker

Example

Parameters

Return type

failAgentSession

Example

Parameters

Return type

fetchAgent

Example

Parameters

Return type

fetchAgentSession

Example

Parameters

Return type

fetchAgentWorker

Example

Parameters

Return type

heartbeatAgentWorker

Example

Parameters

Return type

listAgentActivities

Example

Parameters

Return type

listAgentSessions

Example

Parameters

Return type

listAgentWorkers

Example

Parameters