Conventions API¶

This page defines conventions shared by AI Studio Product API routes. Exact schemas, limits, and optional fields come from the OpenAPI document published by the target deployment.

Base URL and route notation¶

Send requests to the product endpoint used by the AI Studio UI:

{product-endpoint}/{route}

In this reference, :id, :workflow_id, and similar segments are path parameters. Replace the whole segment with the URL-encoded identifier. Product routes shown here include the /newmoi prefix exactly.

Authentication¶

The Product API accepts one caller credential per request:

X-API-Key: <user-scoped-product-api-key>

or:

Authorization: Bearer <product-token>

Do not send a Genesis model key, a browser cookie copied from another environment, or MOI_SYSTEM_API_KEY. API-key calls must receive the same workspace authorization and audit behavior as UI token calls.

Workspace scope¶

Resource operations are workspace-scoped:

X-Workspace-ID: <workspace-id>

Workspace discovery and creation are exceptions because the caller has not selected a workspace yet. Never silently substitute a default workspace. Resource identifiers from one workspace are not valid evidence of access in another.

JSON, uploads, and downloads¶

Use Content-Type: application/json for JSON requests. File upload endpoints may use multipart data or a deployment-issued upload location; file preview, stream, export, and query-result endpoints may return binary data, a stream, or a temporary URL. Follow the response Content-Type and do not assume that every successful response is JSON.

Secrets belong in headers or secret-reference fields defined by the deployed schema. Do not log API keys, provider credentials, connector passwords, session cookies, presigned URLs, or full request bodies that contain them.

Results and long-running operations¶

A successful write can return a resource, an operation record, or only a success envelope. Do not invent an identifier from a name or from an empty write response. Read the resource through its list/detail endpoint before the next dependent call.

Import, export, workflow, knowledge-source, SQL, compute, and agent operations can continue after the initial HTTP response. Retain the returned task, execution, query, or request ID and poll the corresponding status endpoint. Stop only at a documented terminal state. For A2A or Explore streams, stop on the protocol’s terminal event or when the caller cancels the stream.

Pagination and filtering¶

List endpoints do not share one universal request shape. Some use query parameters; others use a JSON filter body. Preserve the server-provided cursor, page, size, total, or continuation value and follow the deployed schema. Unless the API explicitly promises ordering, do not treat the first item as the newest or as a unique name match.

Errors and retries¶

Status	Meaning	Caller action
`400`	Invalid input or business validation failure	Correct the indicated field; do not retry unchanged
`401`	Missing, invalid, or expired identity	Refresh or replace the caller credential
`403`	Workspace or resource action is not allowed	Check workspace selection, role, and resource grants
`404`	Resource is absent or not visible	Recheck the identifier and workspace
`409`	State or version conflict	Read fresh state before submitting again
`429`	Rate limit reached	Honor `Retry-After` when present; otherwise use bounded exponential backoff
`500`, `503`	Server error or temporary unavailability	Retain the request ID and retry only a limited number of times

Retry safe reads and explicitly idempotent operations only. Before retrying a create, run, publish, import, export, or SQL execution, query by the returned operation ID or an API-supported idempotency key. A network timeout does not prove that a write failed.

For troubleshooting, record the HTTP status, server request/correlation ID, workspace ID, route, method, and timestamp. Redact credentials and payload content before sharing diagnostics.