# Djev

> Djev by Maisa is an API for judgments inside software. Give it text, structured JSON, or images, define the questions and possible answers, and receive typed probabilities your code can use. Three answer types: Noul, Choice, and Score.

Djev fits the parts of an application that need to interpret meaning: deciding which workflow applies, whether evidence supports a claim, how relevant a result is, or which pictured option matches a reference. Your application supplies the evidence and owns retrieval, calculations, permissions, and execution. Djev supplies the judgment. It does not generate prose, browse for missing facts, or execute tools.

## Start building

- [Djev skill](https://djev.dev/skill.md): Installable, self-contained guidance for designing questions, combining answers, handling images, and integrating the API. Read this before building with Djev.
- [For agents](https://djev.dev/?view=agents): Copy an installation prompt, understand the three primitives, and explore integration patterns.
- [First request](https://api.djev.dev/docs#quickstart): Copyable cURL, Python, and JavaScript examples. Send an API key directly to POST /v1/request.
- [Request and response](https://api.djev.dev/docs#request): Shared state, named questions, answer objects, and usage.
- [OpenAPI schema](https://api.djev.dev/openapi.json): Exact fields, validation constraints, response envelopes, and account-management operations. Use this when generating types or an HTTP client.
- [Deployment capabilities](https://api.djev.dev/config): Current models, enabled image features, limits, and delivery modes. Read at integration setup; it is not a readiness check before every request.

## Choose the answer shape

- [Noul — whether something holds](https://api.djev.dev/docs#noul): Returns the probability of yes in `answers.<id>.noul`. Use separate Noul questions for labels that can apply together. A value near 0.5 is uncertainty about yes/no, not medium severity.
- [Choice — one of your options](https://api.djev.dev/docs#choice): Returns a winning key, a probability distribution over the provided keys, and confidence. Include a no-match option when the candidates may not cover the input.
- [Score — degree on your rubric](https://api.djev.dev/docs#score): Returns the expected zero-based position on an ordered list of descriptions, plus probabilities, legend, and confidence. With three levels, the range is 0–2 and fractional values are valid.
- [Images in state, questions, and options](https://api.djev.dev/docs#images): Compare a photograph with pictured alternatives, judge a screenshot against a reference, or combine written criteria with visual evidence.
- [Live frames](https://api.djev.dev/docs#webcam): Apply the same request format to current camera frames. Keep one frame in flight and discard stale observations.

## Patterns to explore

- [Design and compose judgments](https://djev.dev/skill.md#design-the-questions): Separate the evidence from the decision, make the possible answers explicit, and keep downstream actions in code.
- [Route an agent or application](https://djev.dev/skill.md#patterns-to-build): Select a supported handler and check whether its required information is present; code validates arguments and dispatches.
- [Rank useful context](https://djev.dev/skill.md#patterns-to-build): Score retrieved candidates against a shared relevance rubric, then sort and select in code.
- [Verify a proposed result](https://djev.dev/skill.md#patterns-to-build): Check a claim, extracted field, or proposed action against supplied evidence; review uncertain or unsupported cases.
- [Build visual interactions](https://djev.dev/skill.md#images-in-questions-and-options): Choose among reference images, check whether an object is visible, or evaluate whether a frame meets a capture criterion.
- [Reuse semantic signals](https://djev.dev/skill.md#compose-answers-in-code): Keep individual judgments so the application can change weights, filters, and thresholds without rerunning unchanged questions.

## Minimal integration

API origin: `https://api.djev.dev`. Request model: `djev`. Response model: `djev-0.1`.

Send `POST /v1/request` with `Authorization: Bearer <DJEV_API_KEY>` and `Content-Type: application/json`. For a direct response, add `Prefer: low-latency` and omit `Idempotency-Key`. Save a random operation ID and the exact request bytes before sending, and pass that ID as `X-Djev-Operation-Id`. Reuse it as `Idempotency-Key` if falling back to durable delivery.

```json
{
  "model": "djev",
  "state": "The customer wants to move their appointment to Friday.",
  "questions": {
    "reschedule": {
      "type": "noul",
      "instructions": "Does the customer ask to change an existing appointment?"
    }
  },
  "options": {"seed": 0}
}
```

Question IDs map responses back to your code; put the full meaning in `instructions`. Independent judgments can share one request, but one question cannot consume another question's answer. Use a subsequent request when an earlier result changes the evidence or candidate set.

## Usage and credits

Prepaid billing is still being prepared. [Usage & credits](https://djev.dev/?view=usage) shows whether billing and purchases are enabled; `/config` also reports `features.prepaid_billing`. When enabled, the rate is **$35 per billion input tokens ($0.035 per million)**. Output tokens are free. All API keys and playground requests for the same account share one balance.

The charged count is `usage.input_tokens` from the canonical successful response: actual prompt tokens across physical model reads, including rendered scaffolding, image-expanded tokens, and context repeated for independent questions, Score levels, or samples. Deduplicated reads count once; cached prompt tokens still count. This is not the token count of the raw user string.

Djev reserves a conservative allowance before execution and settles actual usage once. An unresolved hold reduces available credit until settlement or confirmed release; a client timeout does not refund it. Polling and duplicate delivery of a retained canonical result are not charged again. With billing enabled, reusing the direct `X-Djev-Operation-Id` as the durable `Idempotency-Key`, with exact original bytes, recovers an already charged answer without another charge. When billing is enabled, direct requests require a saved `X-Djev-Operation-Id` and durable requests require a saved `Idempotency-Key`. Missing IDs return 400 before a credit hold or model call. Billing-disabled behavior remains compatible with optional IDs.

On `402 insufficient_credits`, stop automatic retries and direct the user to Usage & credits. For `503 billing_pending` or `billing_unavailable`, keep the same ID and bytes, honor `Retry-After`, and retain unresolved work after bounded waiting. Read the [billing reference](https://api.djev.dev/docs#billing) for details. API users authenticate with their API key; they do not send browser account IDs or perform account lifecycle calls for inference.

## Access and reliable operation

- [Access and keys](https://api.djev.dev/docs#access): Redeem an invitation at djev.dev, save the account recovery key, and create a separate API key for each integration. No email or social login is required. API calls need only the API key; account IDs, recovery keys, and management sessions are not inference credentials. Keep keys in server-side secrets, outside prompts and source control.
- [Durable requests](https://api.djev.dev/docs#durable): For work that must survive connection loss, persist the exact request bytes and a random Idempotency-Key before sending. A POST 202 is a receipt; a GET 200 is a terminal envelope whose status must be inspected. Recover with the same ID and account. Do not create new IDs to work around ambiguous failures.
- [Limits](https://api.djev.dev/docs#limits): Up to 32 questions, 20,000 state characters, one state image, and six image attachments across the request. Check the current schema and capabilities for all bounds.
- [Errors and retries](https://api.djev.dev/docs#errors): Handle `error.code`, honor Retry-After, and bound retries. `capacity_paused` means the administrator has paused serving. Public callers do not manage machines.
- [Options and repeatability](https://api.djev.dev/docs#options): Keep state, question wording, criterion order, model, and options stable when comparing runs. Seed 0 is the default; it does not guarantee identical outputs across every execution.
- [Timing](https://api.djev.dev/docs#timing): Measure total response time at the caller. Model time is only one part; image processing, network transfer, and queueing also contribute.

Djev is in preview. Probabilities and confidence are model estimates, not measured accuracy guarantees. Set thresholds using representative labeled examples and the consequences of each decision. Typed responses make integration predictable; they do not establish that a judgment is correct.