API overview

The Modaic API puts your team's decision criteria to work: route tickets, evaluate agent responses, or check content against a policy. Start with a base model, or create a Model: a versioned decision primitive that treats the base model and its instructions as one artifact. Run it, measure its decisions, and align its instructions with expert feedback.

The base URL is:

https://api.modaic.dev/v1

All request and response bodies use JSON unless an endpoint says otherwise.

Use GET /v1/models to discover base models and the model repositories accessible to your token.

POST /v1/systemone is an alias for POST /v1/decision. Both accept an optional Idempotency-Key; include one when you need retries to replay the same response. Batch decisions and alignments still require a key. See safe retries.

Core workflow

1. Define a decision

   Send a state and one or more typed questions to POST /v1/decision. Questions can return a boolean likelihood, a categorical choice, or a score on a rubric.

2. Create a model

   A model stores your root model, questions, checkpoints, and capture policy in a private, versioned repository.

3. Collect examples

   Decisions made with a repository model can be captured automatically. You can also ingest examples in bulk, then add ground truth and reasoning.

4. Align and measure

   Start an alignment to improve question instructions from annotated examples. An improved alignment creates a new checkpoint that can be evaluated across the full example set.

Resource identifiers

A repository model has two identifiers:

• A human-readable path such as acme/support-triage, used by POST /v1/decision.
• A UUID named modelId in resource URLs for examples, batch decisions, and alignments.

Responses use camelCase for resource fields, such as repositoryId and createdAt. The decision contract uses snake_case for token usage and optional caller-provided identifiers, such as input_tokens and example_id.

Asynchronous operations

Batch decisions and alignments return 202 Accepted with a Location header. Poll that URL until status is completed, failed, or cancelled. Cancelling a job is idempotent and returns 204 No Content.

OpenAPI

The current OpenAPI 3.1 document is available at https://api.modaic.dev/openapi.json.