API reference

All endpoints are mounted at /v1/modules/scaicore/ and authenticate with the standard ScaiGrid bearer token. Responses use ScaiGrid's standard envelope ({ "data": ... } for success, { "error": ... } for failures).

This wrapper hosts ScaiCore programs. The IR and language internals are documented separately at /docs/scaicore.

Cores#

POST /cores#

Create a Core in the caller's tenant.

Returns 201 Created with the new Core.

POST /cores/parse-bundle#

Parse a .scaicore-ir bundle or a JSON IR dict.

• Multipart form with file field.
• Bundles capped at 10 MB.
• Binary bundles must start with the SCIR magic.
• Returns {source, summary} where summary includes name, version, schema_version, flow names, model names, identity name/persona, flags for triggers/plugins, and any embedded avatar.

GET /cores#

List the caller's tenant's Cores. Cursor-paginated (limit, cursor query params).

GET /cores/{core_id}#

Fetch one Core's full config. Tenant-scoped; 404 if not in the caller's tenant.

PUT /cores/{core_id}#

Replace editable fields: name, runtime_mode, source, concurrency_mode, privilege_level, plugins, environment, resource_limits, checkpoint_mode, metadata. Slug, tenant, identity columns are immutable here.

DELETE /cores/{core_id}#

Hard-delete the Core. Unregisters its engine from the in-process registry first.

Lifecycle transitions#

Invalid transitions raise INVALID_CORE_TRANSITION (409).

Publish / unpublish#

POST /cores/{core_id}/publish#

Publish the Core as a FrontendModel in ScaiGrid's catalogue. Body (optional):

1

{ "group_ids": ["mg_xxx", "mg_yyy"] }

Non-super-admins cannot add to global groups or to partner/tenant groups outside their scope; out-of-scope groups are silently dropped. Errors with VALIDATION_ERROR if already published.

POST /cores/{core_id}/unpublish#

Remove the FrontendModel + BackendModel + group memberships. Errors with VALIDATION_ERROR if not currently published.

Avatar#

POST /cores/{core_id}/avatar#

Multipart upload. PNG / JPEG / GIF / WebP / SVG; 2 MB max. Magic-byte validation rejects mismatched content. Stored at scaicore/{tenant_id}/{core_id}/avatar in S3; the Core's avatar_url is set to the proxy path.

GET /cores/{core_id}/avatar#

Public, unauthenticated. Streams the avatar bytes with a 1-hour cache header. Returns 404 if no avatar is set.

Checkpoints#

GET /checkpoints#

List pending checkpoints the caller can act on (assigned to them, their groups, or roles they hold). Cursor-paginated.

GET /checkpoints/all#

List every checkpoint in the tenant. Tenant-admin scope.

GET /checkpoints/{checkpoint_id}#

Fetch one checkpoint's full payload, including parsed assignee, options, context, and resolution (if any).

POST /checkpoints/{checkpoint_id}/resolve#

Errors with CHECKPOINT_ALREADY_RESOLVED (409) if status is not pending.

POST /checkpoints/{checkpoint_id}/cancel#

Cancel without a decision. Status flips to cancelled; the runtime never resumes from this row.

POST /checkpoints/{checkpoint_id}/reassign#

1

{ "assignee": "user:alice@acme", "comment": "..." }

Parses the assignee, rewrites assignee_raw/assignee_type/assignee_resolved, re-fires the notifier.

GET /checkpoints/{checkpoint_id}/history#

Compact event list — created, notification sent, resolved. For full audit, query ScaiGrid's /v1/audit/events?module=scaicore.

Plugins#

GET /cores/{core_id}/plugins#

List the Core's installed plugin entries.

POST /cores/{core_id}/plugins#

Install a plugin entry. Body:

1

{ "alias": "my-plugin", "endpoint": "https://...", "config": {} }

Stored as a JSON entry in the Core's plugins list.

PUT /cores/{core_id}/plugins/{plugin_alias}#

Replace one plugin entry's config.

DELETE /cores/{core_id}/plugins/{plugin_alias}#

Remove the entry.

GET /plugins/available#

Not yet implemented — currently returns { "items": [] }. A plugin marketplace listing is planned but not built.

Debug#

GET /cores/{core_id}/logs#

Stub — returns { "logs": [], "message": "Log retrieval placeholder" }. Persistent log retrieval is not yet wired.

GET /cores/{core_id}/logs/stream#

Not yet implemented — returns 501 with code NOT_IMPLEMENTED. SSE log streaming is planned.

GET /cores/{core_id}/state#

Returns {core_id, status, runtime_mode, concurrency_mode} — the persisted runtime descriptors. Not a live snapshot of the engine.

POST /cores/{core_id}/debug/breakpoint#

Not yet implemented — 501.

POST /cores/{core_id}/debug/step#

Not yet implemented — 501.

POST /cores/{core_id}/debug/inspect#

Not yet implemented — 501.

Events and triggers#

POST /cores/{core_id}/events#

Send a named event to the Core. Body: { "event_name": "...", "data": {} }. Today the call records the dispatch as accepted; the eventing pipeline is wired through the HostEnvironment's EventBus.

GET /cores/{core_id}/events/history#

Not yet implemented — currently returns { "events": [] }. Querying scaicore.runtime.* events from the EventBus is on the roadmap.

POST /cores/{core_id}/triggers#

Register a trigger entry. Body:

1

{ "event_type": "purchase.request", "flow": "approval", "config": {} }

Triggers are stored on the Core's environment.triggers JSON list.

GET /cores/{core_id}/triggers#

List the Core's triggers.

DELETE /cores/{core_id}/triggers/{trigger_id}#

Remove a trigger by its UUID.

Delegation#

POST /cores/{core_id}/delegate#

Delegate a human user's identity to the Core. Body:

1

{ "user_id": "usr_...", "scopes": ["models:use", "files:read"], "expires_at": "2026-12-31T00:00:00Z" }

Requires at least one scope. Flips identity_mode to user_delegated, records the granting user, optional expiry.

GET /cores/{core_id}/delegation#

Returns {identity_mode, delegated_user_id, delegation_scopes, delegation_expires_at, delegation_granted_by}.

PUT /cores/{core_id}/delegation#

Update scopes and/or expires_at on an existing delegation. Errors with DELEGATION_VALIDATION_ERROR if the Core isn't delegated.

POST /cores/{core_id}/revoke-delegation#

Flips identity_mode back to service_account and clears all delegation columns.

API exposure (per-Core programmatic API)#

GET /cores/{core_id}/api/spec#

Returns a compact spec listing the Core's flow names + descriptions, derived from the IR source.flows.

* /cores/{core_id}/api/invoke/{path}#

Not yet implemented — returns 501. Calling Core-defined API paths from outside is on the roadmap.

Conversation logs#

There is no /conversations/... endpoint on this module today. Querying conversations against published Cores is planned but not yet implemented — until then, use the standard ScaiGrid inference accounting / audit pipeline.

Errors#

All endpoints use ScaiGrid's standard error envelope. ScaiCore-specific codes:

For the INVALID_SOURCE_IR and IR-validation codes raised on start, see the ScaiCore language docs at /docs/scaicore.