reference.md

Reference

Entities

client.entities.publishEntity({ ...params }) -> Lattice.Entity

📝 Description

Publish an entity for ingest into the Entities API. Entities created with this method are "owned" by the originator: other sources, such as the UI, may not edit or delete these entities. The server validates entities at API call time and returns an error if the entity is invalid.

An entity ID must be provided when calling this endpoint. If the entity referenced by the entity ID does not exist then it will be created. Otherwise the entity will be updated. An entity will only be updated if its provenance.sourceUpdateTime is greater than the provenance.sourceUpdateTime of the existing entity.

🔌 Usage

await client.entities.publishEntity({});

⚙️ Parameters

request: Lattice.Entity

requestOptions: EntitiesClient.RequestOptions

client.entities.getEntity({ ...params }) -> Lattice.Entity

🔌 Usage

await client.entities.getEntity({
    entityId: "entityId"
});

⚙️ Parameters

request: Lattice.GetEntityRequest

requestOptions: EntitiesClient.RequestOptions

client.entities.overrideEntity({ ...params }) -> Lattice.Entity

📝 Description

Only fields marked with overridable can be overridden. Please refer to our documentation to see the comprehensive list of fields that can be overridden. The entity in the request body should only have a value set on the field specified in the field path parameter. Field paths are rooted in the base entity object and must be represented using lower_snake_case. Do not include "entity" in the field path.

Note that overrides are applied in an eventually consistent manner. If multiple overrides are created concurrently for the same field path, the last writer wins.

🔌 Usage

await client.entities.overrideEntity({
    entityId: "entityId",
    fieldPath: "mil_view.disposition"
});

⚙️ Parameters

request: Lattice.EntityOverride

requestOptions: EntitiesClient.RequestOptions

client.entities.removeEntityOverride({ ...params }) -> Lattice.Entity

📝 Description

This operation clears the override value from the specified field path on the entity.

🔌 Usage

await client.entities.removeEntityOverride({
    entityId: "entityId",
    fieldPath: "mil_view.disposition"
});

⚙️ Parameters

request: Lattice.RemoveEntityOverrideRequest

requestOptions: EntitiesClient.RequestOptions

client.entities.longPollEntityEvents({ ...params }) -> Lattice.EntityEventResponse

📝 Description

This is a long polling API that will first return all pre-existing data and then return all new data as it becomes available. If you want to start a new polling session then open a request with an empty 'sessionToken' in the request body. The server will return a new session token in the response. If you want to retrieve the next batch of results from an existing polling session then send the session token you received from the server in the request body. If no new data is available then the server will hold the connection open for up to 5 minutes. After the 5 minute timeout period, the server will close the connection with no results and you may resume polling with the same session token. If your session falls behind more than 3x the total number of entities in the environment, the server will terminate your session. In this case you must start a new session by sending a request with an empty session token.

🔌 Usage

await client.entities.longPollEntityEvents({
    sessionToken: "sessionToken"
});

⚙️ Parameters

request: Lattice.EntityEventRequest

requestOptions: EntitiesClient.RequestOptions

client.entities.streamEntities({ ...params }) -> core.Stream<Lattice.StreamEntitiesResponse>

📝 Description

Establishes a server-sent events (SSE) connection that streams entity data in real-time. This is a one-way connection from server to client that follows the SSE protocol with text/event-stream content type.

This endpoint enables clients to maintain a real-time view of the common operational picture (COP) by first streaming all pre-existing entities that match filter criteria, then continuously delivering updates as entities are created, modified, or deleted.

The server first sends events with type PREEXISTING for all live entities matching the filter that existed before the stream was open, then streams CREATE events for newly created entities, UPDATE events when existing entities change, and DELETED events when entities are removed. The stream remains open indefinitely unless preExistingOnly is set to true.

Heartbeat messages can be configured to maintain connection health and detect disconnects by setting the heartbeatIntervalMS parameter. These heartbeats help keep the connection alive and allow clients to verify the server is still responsive.

Clients can optimize bandwidth usage by specifying which entity components they need populated using the componentsToInclude parameter. This allows receiving only relevant data instead of complete entities.

The connection automatically recovers from temporary disconnections, resuming the stream where it left off. Unlike polling approaches, this provides real-time updates with minimal latency and reduced server load.

🔌 Usage

const response = await client.entities.streamEntities();
for await (const item of response) {
    console.log(item);
}

⚙️ Parameters

request: Lattice.EntityStreamRequest

requestOptions: EntitiesClient.RequestOptions

Tasks

client.tasks.createTask({ ...params }) -> Lattice.Task

📝 Description

Creates a new Task in the system with the specified parameters.

This method initiates a new task with a unique ID (either provided or auto-generated), sets the initial task state to STATUS_CREATED, and establishes task ownership. The task can be assigned to a specific agent through the Relations field.

Once created, a task enters the lifecycle workflow and can be tracked, updated, and managed through other Tasks API endpoints.

🔌 Usage

await client.tasks.createTask();

⚙️ Parameters

request: Lattice.TaskCreation

requestOptions: TasksClient.RequestOptions

client.tasks.getTask({ ...params }) -> Lattice.Task

📝 Description

Retrieves a specific Task by its ID, with options to select a particular task version or view.

This method returns detailed information about a task including its current status, specification, relations, and other metadata. The response includes the complete Task object with all associated fields.

By default, the method returns the latest definition version of the task from the manager's perspective.

🔌 Usage

await client.tasks.getTask({
    taskId: "taskId"
});

⚙️ Parameters

request: Lattice.GetTaskRequest

requestOptions: TasksClient.RequestOptions

client.tasks.updateTaskStatus({ ...params }) -> Lattice.Task

📝 Description

Updates the status of a Task as it progresses through its lifecycle.

This method allows agents or operators to report the current state of a task, which could include changes to task status, and error information.

Each status update increments the task's status_version. When updating status, clients must provide the current version to ensure consistency. The system rejects updates with mismatched versions to prevent race conditions.

Terminal states (STATUS_DONE_OK and STATUS_DONE_NOT_OK) are permanent; once a task reaches these states, no further updates are allowed.

🔌 Usage

await client.tasks.updateTaskStatus({
    taskId: "taskId"
});

⚙️ Parameters

request: Lattice.TaskStatusUpdate

requestOptions: TasksClient.RequestOptions

client.tasks.cancelTask({ ...params }) -> Lattice.Task

📝 Description

Cancels a task by marking it for cancellation in the system.

This method initiates task cancellation based on the task's current state:

• If the task has not been sent to an agent, it cancels immediately and transitions the task to a terminal state (STATUS_DONE_NOT_OK with ERROR_CODE_CANCELLED).
• If the task has already been sent to an agent, the cancellation request is routed to the agent. The agent is then responsible for deciding whether cancellation is possible or not:
  • If the task can be cancelled, the agent must use UpdateTaskStatus and set the task status to STATUS_DONE_NOT_OK.
  • If the task cannot be cancelled, the agent must use UpdateTaskStatus to attach a TaskError to the task with the error code ERROR_CODE_REJECTED and a message explaining why the task cannot be cancelled.

🔌 Usage

await client.tasks.cancelTask({
    taskId: "taskId"
});

⚙️ Parameters

request: Lattice.TaskCancellation

requestOptions: TasksClient.RequestOptions

client.tasks.queryTasks({ ...params }) -> Lattice.TaskQueryResults

📝 Description

Searches for Tasks that match specified filtering criteria and returns matching tasks in paginated form.

This method allows filtering tasks based on multiple criteria including:

• Parent task relationships
• Task status (with inclusive or exclusive filtering)
• Update time ranges
• Task view (manager or agent perspective)
• Task assignee
• Task type (via exact URL matches or prefix matching)

Results are returned in pages. When more results are available than can be returned in a single response, a page_token is provided that can be used in subsequent requests to retrieve the next set of results.

By default, this returns the latest task version for each matching task from the manager's perspective.

🔌 Usage

await client.tasks.queryTasks();

⚙️ Parameters

request: Lattice.TaskQuery

requestOptions: TasksClient.RequestOptions

client.tasks.streamTasks({ ...params }) -> core.Stream<Lattice.StreamTasksResponse>

📝 Description

Establishes a server streaming connection that delivers task updates in real-time using Server-Sent Events (SSE).

The stream delivers all existing non-terminal tasks when first connected, followed by real-time updates for task creation and status changes. Additionally, heartbeat messages are sent periodically to maintain the connection.

🔌 Usage

const response = await client.tasks.streamTasks();
for await (const item of response) {
    console.log(item);
}

⚙️ Parameters

request: Lattice.TaskStreamRequest

requestOptions: TasksClient.RequestOptions

client.tasks.listenAsAgent({ ...params }) -> Lattice.AgentRequest

📝 Description

Establishes a server streaming connection that delivers tasks to taskable agents for execution.

This method creates a persistent connection from Tasks API to an agent, allowing the server to push tasks to the agent as they become available. The agent receives a stream of tasks that match its selector criteria (entity IDs).

The stream delivers three types of requests:

• ExecuteRequest: Contains a new task for the agent to execute
• CancelRequest: Indicates a task should be canceled
• CompleteRequest: Indicates a task should be completed

This is the primary method for taskable agents to receive and process tasks in real-time. Agents should maintain this connection and process incoming tasks according to their capabilities.

When an agent receives a task, it should update the task status using the UpdateStatus endpoint to provide progress information back to Tasks API.

This is a long polling API that will block until a new task is ready for delivery. If no new task is available then the server will hold on to your request for up to 5 minutes, after that 5 minute timeout period you will be expected to reinitiate a new request.

🔌 Usage

await client.tasks.listenAsAgent();

⚙️ Parameters

request: Lattice.AgentListener

requestOptions: TasksClient.RequestOptions

client.tasks.streamAsAgent({ ...params }) -> core.Stream<Lattice.StreamAsAgentResponse>

📝 Description

Establishes a server streaming connection that delivers tasks to taskable agents for execution using Server-Sent Events (SSE).

This method creates a connection from the Tasks API to an agent that streams relevant tasks to the listener agent. The agent receives a stream of tasks that match the entities specified by the tasks' selector criteria.

The stream delivers three types of requests:

• ExecuteRequest: Contains a new task for the agent to execute
• CancelRequest: Indicates a task should be canceled
• CompleteRequest: Indicates a task should be completed

Additionally, heartbeat messages are sent periodically to maintain the connection.

This is recommended method for taskable agents to receive and process tasks in real-time. Agents should maintain connection to this stream and process incoming tasks according to their capabilities.

When an agent receives a task, it should update the task status using the UpdateStatus endpoint to provide progress information back to Tasks API.

🔌 Usage

const response = await client.tasks.streamAsAgent();
for await (const item of response) {
    console.log(item);
}

⚙️ Parameters

request: Lattice.AgentStreamRequest

requestOptions: TasksClient.RequestOptions

client.tasks.streamManualControlFrames({ ...params }) -> core.Stream<Lattice.StreamManualControlFramesResponse>

📝 Description

Establishes a server streaming connection that delivers manual control frames to agents using server-sent events (SSE).

This endpoint streams manual control frames, for example, for joystick movements, for a specific task to the executing agent. The agent should open this stream before reporting STATUS_EXECUTING to ensure it is ready to receive control input when the operator begins sending frames.

Each frame includes epoch and sequence metadata for handling concurrent control sessions and detecting stale or out-of-order frames. Heartbeat messages are sent periodically to maintain the connection.

The stream terminates automatically when the task reaches a terminal state (STATUS_DONE_OK or STATUS_DONE_NOT_OK).

🔌 Usage

const response = await client.tasks.streamManualControlFrames({
    taskId: "taskId"
});
for await (const item of response) {
    console.log(item);
}

⚙️ Parameters

request: Lattice.ManualControlStreamRequest

requestOptions: TasksClient.RequestOptions

Objects

client.objects.listObjects({ ...params }) -> core.Page<Lattice.PathMetadata, Lattice.ListResponse>

📝 Description

Lists objects in your environment. You can define a prefix to list a subset of your objects. If you do not set a prefix, Lattice returns all available objects. By default this endpoint will list local objects only.

🔌 Usage

const pageableResponse = await client.objects.listObjects();
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.objects.listObjects();
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Lattice.ListObjectsRequest

requestOptions: ObjectsClient.RequestOptions

client.objects.getObject({ ...params }) -> core.BinaryResponse

📝 Description

Fetches an object from your environment using the objectPath path parameter.

🔌 Usage

await client.objects.getObject({
    objectPath: "objectPath"
});

⚙️ Parameters

request: Lattice.GetObjectRequest

requestOptions: ObjectsClient.RequestOptions

client.objects.uploadObject(uploadable, objectPath) -> Lattice.PathMetadata

📝 Description

Uploads an object. The object must be 1 GiB or smaller.

🔌 Usage

await client.objects.uploadObject(createReadStream("path/to/file"), undefined);

⚙️ Parameters

uploadable: core.file.Uploadable

objectPath: string

requestOptions: ObjectsClient.RequestOptions

client.objects.deleteObject({ ...params }) -> void

📝 Description

Deletes an object from your environment given the objectPath path parameter.

🔌 Usage

await client.objects.deleteObject({
    objectPath: "objectPath"
});

⚙️ Parameters

request: Lattice.DeleteObjectRequest

requestOptions: ObjectsClient.RequestOptions

client.objects.getObjectMetadata({ ...params }) -> Headers

📝 Description

Returns metadata for a specified object path. Use this to fetch metadata such as object size (size_bytes), its expiry time (expiry_time), or its latest update timestamp (last_updated_at).

🔌 Usage

await client.objects.getObjectMetadata({
    objectPath: "objectPath"
});

⚙️ Parameters

request: Lattice.GetObjectMetadataRequest

requestOptions: ObjectsClient.RequestOptions

oauth

client.oauth.getToken({ ...params }) -> Lattice.GetTokenResponse

📝 Description

Gets a new short-lived token using the specified client credentials

🔌 Usage

await client.oauth.getToken({});

⚙️ Parameters

request: Lattice.GetTokenRequest

requestOptions: OauthClient.RequestOptions