---
title: "service"
description: "The service namespace — the engine's Luau API reference for service."
section: "API Reference"
slug: "api-service"
canonical: "https://origozero.ai/docs/api-service"
updated: "2026-09-05T23:13:47.142469443+00:00"
tags: ["api", "reference"]
---

# service

The `service` namespace — 21 functions.

## globals/service/authenticated {#globals-service-authenticated}

```lua
service.authenticated() -> boolean
```

Whether a platform identity (JWT) is available to attach to
service calls. Returns only a boolean — never the token.

**Returns** `boolean` — True if a caller identity is available.

```lua
if not service.authenticated() then error("link ZeroMind") end
```

## globals/service/balance {#globals-service-balance}

```lua
service.balance() -> string?
```

Read the caller's credit balance from ZeroMind. Returns a
promise handle for `task.await()` resolving the balance JSON, or nil
when the gateway is unconfigured or no caller identity is available.

**Returns** `string?` — Promise handle for `task.await()`, or nil if not ready.

```lua
local h = service.balance(); local raw = h and task.await(h)
```

## globals/service/gatewayConfigured {#globals-service-gatewayconfigured}

```lua
service.gatewayConfigured() -> boolean
```

Whether the ZeroMind service gateway has been configured.
Service handlers use this to distinguish "gateway not configured"
from "not signed in" when `invoke` returns nil.

**Returns** `boolean` — True if the gateway base URL is set.

```lua
if not service.gatewayConfigured() then error("no gateway") end
```

## globals/service/invoke {#globals-service-invoke}

```lua
service.invoke(offering: string, endpoint: string, opts: InvokeOpts?) -> string?
```

Invoke a provider offering's logical endpoint through ZeroMind.
Returns a promise handle for `task.await()` resolving the
InvokeResponse JSON, or nil when the gateway is unconfigured or no
caller identity is available. The JWT and real upstream URL are
never exposed to Luau.

**Parameters**

- `offering` `string` — Fully-qualified offering identity `provider/name` (e.g. "origozero/mesh_gen").
- `endpoint` `string` — Logical endpoint name (e.g. "create_preview").
- `opts` `InvokeOpts` _(optional)_ — `{ params?, headers?, body?, idempotency_key? }`.

**Returns** `string?` — Promise handle for `task.await()`, or nil if not ready.

```lua
local h = service.invoke("origozero/mesh_gen", "create_preview", { body = { prompt = p } })
```

## globals/service/jobStatus {#globals-service-jobstatus}

```lua
service.jobStatus(jobId: string) -> string?
```

Poll a submitted service job. Returns a promise handle for
`task.await()` resolving the JobStatusResponse JSON `{ job_id, status,
result?, error? }`: `status` walks `pending`/`running` -> `succeeded`
(with `result`, the same InvokeResponse `invoke` returns) or `failed`
(with `error`). nil when the gateway is unconfigured or no caller
identity is available.

**Parameters**

- `jobId` `string` — Job id returned by `submitJob`.

**Returns** `string?` — Promise handle resolving the job status JSON, or nil if not ready.

```lua
local h = service.jobStatus(jobId); local raw = h and task.await(h)
```

## globals/service/submitJob {#globals-service-submitjob}

```lua
service.submitJob(offering: string, endpoint: string, opts: InvokeOpts?) -> string?
```

Submit a durable async invocation of an offering endpoint. Same
arguments as `invoke`, but the provider round-trip runs server-side
(off this connection), so a slow synchronous provider or a dropped
link no longer loses the result. Returns a promise handle for
`task.await()` resolving `{ job_id, status }`; poll it with
`jobStatus`. nil when the gateway is unconfigured or no caller
identity is available.

**Parameters**

- `offering` `string` — Fully-qualified offering identity `provider/name` (e.g. "origozero/mesh_gen").
- `endpoint` `string` — Logical endpoint name (e.g. "create_preview").
- `opts` `InvokeOpts` _(optional)_ — `{ params?, headers?, body?, idempotency_key? }`.

**Returns** `string?` — Promise handle resolving `{ job_id, status }`, or nil if not ready.

```lua
local h = service.submitJob("origozero/mesh_gen", "create_preview", { body = { prompt = p } })
```

## modules/service/README {#modules-service-readme}

```lua
require("@builtin/modules/api/engine/service") -- service (also available as global 'service')
```

Credit-metered service invoke. Public Luau surface over the `__service` Internal FFI namespace.

Usage: local service = require("@builtin/modules/api/engine/service")
Also available as global: service

## modules/service/authenticated {#modules-service-authenticated}

```lua
authenticated(): boolean
```

Whether a platform identity (JWT) is available to attach to
service calls. Returns only a boolean — never the token.

```lua
if not service.authenticated() then error("link ZeroMind") end
```

## modules/service/balance {#modules-service-balance}

```lua
balance(): string?
```

Read the caller's credit balance from ZeroMind. Returns a
promise handle for `task.await()` resolving the balance JSON, or nil
when the gateway is unconfigured or no caller identity is available.

```lua
local h = service.balance(); local raw = h and task.await(h)
```

## modules/service/configureGateway {#modules-service-configuregateway}

```lua
configureGateway(baseUrl: string): boolean
```

TRUSTED ONLY. Set the ZeroMind base URL that `service.invoke`
and `service.balance` target. The trusted-VM auth bootstrap calls
this with the resolved issuer.

**Parameters**

- `baseUrl` `string` — ZeroMind base URL (e.g. "https://origozero.ai").

```lua
service.configureGateway("https://origozero.ai")
```

## modules/service/configureWorld {#modules-service-configureworld}

```lua
configureWorld(guid: string): boolean
```

TRUSTED ONLY. Set the bound world guid attached to metered
service invocations, so the credit ledger attributes each charge to
the world it happened in. The trusted-VM world-load hook calls this
on every bind so a runtime world switch re-points attribution.

**Parameters**

- `guid` `string` — The bound world's guid.

```lua
service.configureWorld(world.guid())
```

## modules/service/gatewayConfigured {#modules-service-gatewayconfigured}

```lua
gatewayConfigured(): boolean
```

Whether the ZeroMind service gateway has been configured.
Service handlers use this to distinguish "gateway not configured"
from "not signed in" when `invoke` returns nil.

```lua
if not service.gatewayConfigured() then error("no gateway") end
```

## modules/service/invoke {#modules-service-invoke}

```lua
invoke(offering: string, endpoint: string, opts: InvokeOpts?): string?
```

Invoke a provider offering's logical endpoint through ZeroMind.
Returns a promise handle for `task.await()` resolving the
InvokeResponse JSON, or nil when the gateway is unconfigured or no
caller identity is available. The JWT and real upstream URL are
never exposed to Luau.

**Parameters**

- `offering` `string` — Fully-qualified offering identity `provider/name` (e.g. "origozero/mesh_gen").
- `endpoint` `string` — Logical endpoint name (e.g. "create_preview").
- `opts` `InvokeOpts?` _(optional)_ — `{ params?, headers?, body?, idempotency_key? }`.

```lua
local h = service.invoke("origozero/mesh_gen", "create_preview", { body = { prompt = p } })
```

## modules/service/jobStatus {#modules-service-jobstatus}

```lua
jobStatus(jobId: string): string?
```

Poll a submitted service job. Returns a promise handle for
`task.await()` resolving the JobStatusResponse JSON `{ job_id, status,
result?, error? }`: `status` walks `pending`/`running` -> `succeeded`
(with `result`, the same InvokeResponse `invoke` returns) or `failed`
(with `error`). nil when the gateway is unconfigured or no caller
identity is available.

**Parameters**

- `jobId` `string` — Job id returned by `submitJob`.

```lua
local h = service.jobStatus(jobId); local raw = h and task.await(h)
```

## modules/service/submitJob {#modules-service-submitjob}

```lua
submitJob(offering: string, endpoint: string, opts: InvokeOpts?): string?
```

Submit a durable async invocation of an offering endpoint. Same
arguments as `invoke`, but the provider round-trip runs server-side
(off this connection), so a slow synchronous provider or a dropped
link no longer loses the result. Returns a promise handle for
`task.await()` resolving `{ job_id, status }`; poll it with
`jobStatus`. nil when the gateway is unconfigured or no caller
identity is available.

**Parameters**

- `offering` `string` — Fully-qualified offering identity `provider/name` (e.g. "origozero/mesh_gen").
- `endpoint` `string` — Logical endpoint name (e.g. "create_preview").
- `opts` `InvokeOpts?` _(optional)_ — `{ params?, headers?, body?, idempotency_key? }`.

```lua
local h = service.submitJob("origozero/mesh_gen", "create_preview", { body = { prompt = p } })
```

## typed/builtin//modules/api/engine/service/service/authenticated {#typed-builtin-modules-api-engine-service-service-authenticated}

```lua
service.authenticated() -> boolean
```

Whether a platform identity (JWT) is available to attach to
service calls. Returns only a boolean — never the token.

**Returns** `boolean` — True if a caller identity is available.

```lua
if not service.authenticated() then error("link ZeroMind") end
```

## typed/builtin//modules/api/engine/service/service/balance {#typed-builtin-modules-api-engine-service-service-balance}

```lua
service.balance() -> string?
```

Read the caller's credit balance from ZeroMind. Returns a
promise handle for `task.await()` resolving the balance JSON, or nil
when the gateway is unconfigured or no caller identity is available.

**Returns** `string?` — Promise handle for `task.await()`, or nil if not ready.

```lua
local h = service.balance(); local raw = h and task.await(h)
```

## typed/builtin//modules/api/engine/service/service/gatewayConfigured {#typed-builtin-modules-api-engine-service-service-gatewayconfigured}

```lua
service.gatewayConfigured() -> boolean
```

Whether the ZeroMind service gateway has been configured.
Service handlers use this to distinguish "gateway not configured"
from "not signed in" when `invoke` returns nil.

**Returns** `boolean` — True if the gateway base URL is set.

```lua
if not service.gatewayConfigured() then error("no gateway") end
```

## typed/builtin//modules/api/engine/service/service/invoke {#typed-builtin-modules-api-engine-service-service-invoke}

```lua
service.invoke(offering: string, endpoint: string, opts: InvokeOpts?) -> string?
```

Invoke a provider offering's logical endpoint through ZeroMind.
Returns a promise handle for `task.await()` resolving the
InvokeResponse JSON, or nil when the gateway is unconfigured or no
caller identity is available. The JWT and real upstream URL are
never exposed to Luau.

**Parameters**

- `offering` `string` — Fully-qualified offering identity `provider/name` (e.g. "origozero/mesh_gen").
- `endpoint` `string` — Logical endpoint name (e.g. "create_preview").
- `opts` `InvokeOpts` _(optional)_ — `{ params?, headers?, body?, idempotency_key? }`.

**Returns** `string?` — Promise handle for `task.await()`, or nil if not ready.

```lua
local h = service.invoke("origozero/mesh_gen", "create_preview", { body = { prompt = p } })
```

## typed/builtin//modules/api/engine/service/service/jobStatus {#typed-builtin-modules-api-engine-service-service-jobstatus}

```lua
service.jobStatus(jobId: string) -> string?
```

Poll a submitted service job. Returns a promise handle for
`task.await()` resolving the JobStatusResponse JSON `{ job_id, status,
result?, error? }`: `status` walks `pending`/`running` -> `succeeded`
(with `result`, the same InvokeResponse `invoke` returns) or `failed`
(with `error`). nil when the gateway is unconfigured or no caller
identity is available.

**Parameters**

- `jobId` `string` — Job id returned by `submitJob`.

**Returns** `string?` — Promise handle resolving the job status JSON, or nil if not ready.

```lua
local h = service.jobStatus(jobId); local raw = h and task.await(h)
```

## typed/builtin//modules/api/engine/service/service/submitJob {#typed-builtin-modules-api-engine-service-service-submitjob}

```lua
service.submitJob(offering: string, endpoint: string, opts: InvokeOpts?) -> string?
```

Submit a durable async invocation of an offering endpoint. Same
arguments as `invoke`, but the provider round-trip runs server-side
(off this connection), so a slow synchronous provider or a dropped
link no longer loses the result. Returns a promise handle for
`task.await()` resolving `{ job_id, status }`; poll it with
`jobStatus`. nil when the gateway is unconfigured or no caller
identity is available.

**Parameters**

- `offering` `string` — Fully-qualified offering identity `provider/name` (e.g. "origozero/mesh_gen").
- `endpoint` `string` — Logical endpoint name (e.g. "create_preview").
- `opts` `InvokeOpts` _(optional)_ — `{ params?, headers?, body?, idempotency_key? }`.

**Returns** `string?` — Promise handle resolving `{ job_id, status }`, or nil if not ready.

```lua
local h = service.submitJob("origozero/mesh_gen", "create_preview", { body = { prompt = p } })
```