> ## Documentation Index > Fetch the complete documentation index at: https://docs.moonbounce.ai/llms.txt > Use this file to discover all available pages before exploring further. # Read a decision procedure or role brief > Start with topic procedure.entry. For planned work, follow plan.stages[].guidance.topic using plan_id; the plan pins the release. Follow related_guidance arguments for role/shared procedures tied to the same plan and owning stage. Standalone reads may name release instead. Reads only, no model calls or workflow transitions. Missing guidance never falls back to another release. ## OpenAPI ````yaml /openapi.json get /v1/decision-guidance openapi: 3.1.0 info: title: Moonbounce Decisions API version: 0.0.0 description: >- Moonbounce decisions: evaluate an item's state against a decision structure (System One questions, attributes you supply and aggregations over both), record feedback and import labeled examples, review a ranked queue, and improve the structure through suggestions that ship as code diffs, each with a preview (backtest) and an evidence label. **Authentication.** Send an API key as `Authorization: Bearer ` on every operation except `GET /health` and `POST /v1/validate`, and an upload's own `url` (`PUT /v1/uploads/{upload_id}/{token}`), which its token authorizes. Call the API from a server, never a browser: a key must not reach one, and the API sends no CORS headers. A key belongs to one organization and one environment: production, or test for a key with the `env:test` permission. Test traffic never counts as production traffic. **Requests.** JSON bodies (`Content-Type: application/json`) of at most 1 MB, parsed strictly: duplicate keys, lone surrogates, integers outside ±(2^53 - 1), `__proto__` keys, U+0000 and nesting deeper than 64 are a 400. A larger dataset, or a file you'd rather not paste, goes up as a file: `createUpload` answers a URL to PUT it to. **Retries.** Send an `Idempotency-Key` on every POST under /v1 that takes one (all but `POST /v1/validate`, `POST /v1/review/items/fill`, whose retry is another fill within the day's budget, and `createUpload`, whose retry is another upload). Keep it for the request's retries. The same key with the same request returns the first stored result, marked `Idempotent-Replayed: true`, for 24 hours (410 if that result was since deleted); with another request it is 422 IDEMPOTENCY_KEY_REUSED. Keys are scoped to the organization and environment across every operation, so use a fresh key per request. A request that failed before its result was stored runs again when retried. 429 and 503 under /v1 may carry `Retry-After` (seconds); a daily QUOTA_EXCEEDED cap instead names its reset time. **Lists.** A list answers one page: `{environment, items, next_cursor, has_more}` (named `Page`), in the order the operation states. Pass `next_cursor` back as `cursor`, with the same filters, while `has_more` is true; on the last page `next_cursor` is null. `limit` defaults to 50 and is at most 100, with these exceptions: cases go up to 200 a page (a run's batch; 50 with content), suggestions default to 20, since each carries its whole candidate structure and evidence, and the review queue (a reviewer's screen) defaults to 20, at most 50. **Errors.** Every error under /v1 is `{"error": {"type", "message", "reason"?, "param"?, "details"?}}` (ErrorBody); `GET /health` answers its own shape. Every response carries a `Request-Id` header. Rate limits apply per key, and per client IP for requests without a valid key; a 429 RATE_LIMITED carries `Retry-After`. servers: - url: https://api.moonbounce.ai description: Production security: [] tags: - name: Evaluate description: Run one item through a decision and read evaluations back. Start here. - name: Decisions description: >- Validate a decision file, register its versions, and read decisions and versions. - name: Feedback description: >- Say what the right answer was, import labeled examples, and read feedback and cases. - name: Suggestions description: Ask for a better version of a decision, and follow the improvement loop. - name: Uploads description: >- Send a dataset or structure file once, then name it in runs, imports and registrations. - name: Previews & tests description: >- Replay a structure change over past cases, and score a version over many items. - name: Models description: List the models a decision can run on and choose one. - name: Objective description: >- Set what a decision optimizes for, then judge runs and tune cuts against it. - name: Usage description: What a decision's model calls cost. - name: Account description: Identify your key, and check that the API is up. paths: /v1/decision-guidance: get: tags: - Decisions summary: Read a decision procedure or role brief description: >- Start with topic procedure.entry. For planned work, follow plan.stages[].guidance.topic using plan_id; the plan pins the release. Follow related_guidance arguments for role/shared procedures tied to the same plan and owning stage. Standalone reads may name release instead. Reads only, no model calls or workflow transitions. Missing guidance never falls back to another release. operationId: getDecisionGuidance parameters: - schema: $ref: '#/components/schemas/IntakeTopic' required: true name: topic in: query - schema: $ref: '#/components/schemas/IntakePlanId' required: false name: plan_id in: query - schema: $ref: '#/components/schemas/IntakeRelease' required: false name: release in: query - schema: $ref: '#/components/schemas/IntakeStageId' required: false name: stage_id in: query responses: '200': description: Versioned guidance and references content: application/json: schema: $ref: '#/components/schemas/DecisionGuidance' '400': description: 'Invalid request: `param` names the field at fault when one applies' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '401': description: Missing or invalid API key (reason KEY_INVALID) content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '403': description: The key may not do this content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '404': description: >- Not found, or not visible to this key (reason PLAN_UNKNOWN or GUIDANCE_UNKNOWN) x-error-reasons: - PLAN_UNKNOWN - GUIDANCE_UNKNOWN content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '409': description: Conflict with the current state content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '429': description: >- RATE_LIMITED: retry after Retry-After seconds; QUOTA_EXCEEDED: details.reset_at gives the daily reset time (no Retry-After) headers: Retry-After: schema: type: string description: Seconds to wait before retrying, when waiting helps. required: false description: Seconds to wait before retrying, when waiting helps. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '503': description: >- Temporarily unavailable, with Retry-After (for example reason AUTH_UNAVAILABLE, ENGINE_UNAVAILABLE or STORE_UNAVAILABLE): retry with the same Idempotency-Key headers: Retry-After: schema: type: string description: Seconds to wait before retrying, when waiting helps. required: true description: Seconds to wait before retrying, when waiting helps. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' security: - bearerAuth: - decisions:develop components: schemas: IntakeTopic: type: string pattern: ^(stage|role|procedure)\.[a-z][a-z0-9_.-]{0,100}$ IntakePlanId: type: string pattern: ^dpl_[A-Za-z0-9-]{1,80}$ IntakeRelease: type: string minLength: 1 maxLength: 80 pattern: ^[A-Za-z0-9][A-Za-z0-9._/-]*$ IntakeStageId: type: string enum: - objective - case_audit - reconcile - brief - probes - label_check - cases - first_version - baseline - refine - red_team - blind_check - import - integration DecisionGuidance: type: object properties: schema: type: string enum: - moonbounce.decision-guidance/1 topic: $ref: '#/components/schemas/IntakeTopicOutput' title: type: string minLength: 1 maxLength: 200 release: $ref: '#/components/schemas/IntakeReleaseOutput' adapter_release: $ref: '#/components/schemas/IntakeReleaseOutput' intake_release: $ref: '#/components/schemas/IntakeReleaseOutput' plan_id: anyOf: - $ref: '#/components/schemas/IntakePlanIdOutput' - type: 'null' stage_id: anyOf: - $ref: '#/components/schemas/IntakeStageIdOutput' - type: 'null' audience: type: string enum: - orchestrator - worker content: type: string minLength: 1 maxLength: 32768 content_sha256: $ref: '#/components/schemas/IntakeSha256' related_guidance: type: array items: $ref: '#/components/schemas/DecisionGuidanceLink' maxItems: 64 required: - schema - topic - title - release - adapter_release - intake_release - plan_id - stage_id - audience - content - content_sha256 - related_guidance additionalProperties: true x-moonbounce-sdk-known-fields: true ErrorBody: type: object properties: error: type: object properties: type: $ref: '#/components/schemas/ErrorType' reason: type: string pattern: ^[A-Z][A-Z0-9_]+$ description: >- Set where a caller can act on it, one of the reasons in the ErrorReason schema. New reasons may be added: treat an unknown one by the status and `type`. message: type: string description: For people; don't parse it. param: type: string description: >- The request field at fault, as a dotted path (`attribute_values.region`, `claims.1.value`). details: type: object properties: issues: type: array items: $ref: '#/components/schemas/ErrorIssue' additionalProperties: {} required: - type - message additionalProperties: true x-moonbounce-sdk-known-fields: true required: - error additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeTopicOutput: type: string pattern: ^(stage|role|procedure)\.[a-z][a-z0-9_.-]{0,100}$ IntakeReleaseOutput: type: string minLength: 1 maxLength: 80 pattern: ^[A-Za-z0-9][A-Za-z0-9._/-]*$ IntakePlanIdOutput: type: string pattern: ^dpl_[A-Za-z0-9-]{1,80}$ IntakeStageIdOutput: type: string enum: - objective - case_audit - reconcile - brief - probes - label_check - cases - first_version - baseline - refine - red_team - blind_check - import - integration IntakeSha256: type: string pattern: ^[0-9a-f]{64}$ DecisionGuidanceLink: type: object properties: topic: $ref: '#/components/schemas/IntakeTopicOutput' title: type: string minLength: 1 maxLength: 200 arguments: $ref: '#/components/schemas/GetDecisionGuidanceQuery' required: - topic - title - arguments additionalProperties: true x-moonbounce-sdk-known-fields: true ErrorType: type: string enum: - invalid_request - authentication - permission_denied - not_found - conflict - rate_limited - engine_failed - unavailable - internal ErrorIssue: type: object properties: param: type: string code: type: string pattern: ^[A-Z][A-Z0-9_]+$ description: >- Stable, extensible issue code; unknown codes still have a parameter and human-readable message. message: type: string required: - param - code - message additionalProperties: true x-moonbounce-sdk-known-fields: true GetDecisionGuidanceQuery: type: object properties: topic: $ref: '#/components/schemas/IntakeTopicOutput' plan_id: $ref: '#/components/schemas/IntakePlanIdOutput' release: $ref: '#/components/schemas/IntakeReleaseOutput' stage_id: $ref: '#/components/schemas/IntakeStageIdOutput' required: - topic additionalProperties: true x-moonbounce-sdk-known-fields: true securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key, sent as `Authorization: Bearer `. Each operation lists the scope its key needs: `decisions:evaluate` (evaluate and read evaluations), `decisions:feedback` (your app's feedback) or `decisions:develop` (everything else, including owner feedback and the review queue). An operation listing no scope takes any scoped key. A key with no scope, or without the operation's, gets 403 INSUFFICIENT_SCOPE. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.