> ## 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. # List a decision's advisory plans > Reads only, newest first. Cursors bind the calling organization, environment and decision. A page is also bounded by snapshot bytes; follow next_cursor while has_more. A decision without plans returns an empty page. ## OpenAPI ````yaml /openapi.json get /v1/decisions/{decision_id}/plans 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/decisions/{decision_id}/plans: get: tags: - Decisions summary: List a decision's advisory plans description: >- Reads only, newest first. Cursors bind the calling organization, environment and decision. A page is also bounded by snapshot bytes; follow next_cursor while has_more. A decision without plans returns an empty page. operationId: listDecisionPlans parameters: - schema: $ref: '#/components/schemas/DecisionId' required: true description: >- A name you choose for this decision, such as `refund-exception`: a lowercase letter, then up to 127 of `a-z 0-9 _ . -`. Unique in your organization and shared by its test and production keys. The first registration or evaluation under a new one creates the decision. name: decision_id in: path - schema: type: integer minimum: 1 maximum: 100 default: 50 required: false name: limit in: query - schema: type: string minLength: 1 maxLength: 2048 required: false name: cursor in: query responses: '200': description: A scoped page of immutable plans content: application/json: schema: $ref: '#/components/schemas/IntakePlanPage' '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' '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: DecisionId: type: string pattern: ^[a-z][a-z0-9_.-]{0,127}$ description: >- A name you choose for this decision, such as `refund-exception`: a lowercase letter, then up to 127 of `a-z 0-9 _ . -`. Unique in your organization and shared by its test and production keys. The first registration or evaluation under a new one creates the decision. IntakePlanPage: type: object properties: environment: type: string enum: - production - test items: type: array items: $ref: '#/components/schemas/DecisionPlan' maxItems: 100 next_cursor: anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' has_more: type: boolean required: - environment - items - next_cursor - has_more 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 DecisionPlan: type: object properties: schema: type: string enum: - moonbounce.intake-plan/1 id: $ref: '#/components/schemas/IntakePlanIdOutput' environment: type: string enum: - production - test decision_id: $ref: '#/components/schemas/IntakeDecisionId' parent_plan_id: anyOf: - $ref: '#/components/schemas/IntakePlanIdOutput' - type: 'null' revision: type: integer minimum: 1 created_at: type: string format: date-time intake_release: $ref: '#/components/schemas/IntakeRelease' planner_release: $ref: '#/components/schemas/IntakeRelease' guidance_release: $ref: '#/components/schemas/IntakeRelease' input: $ref: '#/components/schemas/IntakeDocument' route: type: string enum: - build - improve - assess - investigate - undetermined approach: type: string enum: - reconcile - policy - examples - discover deliverable: type: string enum: - draft - measured_candidate - assessment - investigation budget: $ref: '#/components/schemas/IntakeConstraints' stages: type: array items: $ref: '#/components/schemas/IntakeStage' minItems: 14 maxItems: 14 applied_rules: type: array items: type: string pattern: ^R([1-9]|10)$ minItems: 1 gaps: type: array items: $ref: '#/components/schemas/IntakeGap' maxItems: 128 source_upload: $ref: '#/components/schemas/IntakeSourceUpload' assumptions: type: array items: $ref: '#/components/schemas/IntakeAssumption' maxItems: 1024 operation: anyOf: - type: string enum: - create - type: string enum: - revise - type: string enum: - assess - type: string enum: - investigate - type: - object - 'null' enum: - null - type: 'null' adapter_release: $ref: '#/components/schemas/IntakeRelease' evidence_status: type: array items: $ref: '#/components/schemas/IntakeEvidenceStatus' maxItems: 128 required: - schema - id - environment - decision_id - parent_plan_id - revision - created_at - intake_release - planner_release - guidance_release - input - route - approach - deliverable - budget - stages - applied_rules - gaps - source_upload - assumptions - operation - adapter_release - evidence_status 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 IntakePlanIdOutput: type: string pattern: ^dpl_[A-Za-z0-9-]{1,80}$ IntakeDecisionId: type: string pattern: ^[a-z][a-z0-9_.-]{0,127}$ IntakeRelease: type: string minLength: 1 maxLength: 80 pattern: ^[A-Za-z0-9][A-Za-z0-9._/-]*$ IntakeDocument: type: object properties: schema: type: string enum: - moonbounce.decision-intake/1 decision_id: $ref: '#/components/schemas/IntakeDecisionId' intake_release: $ref: '#/components/schemas/IntakeRelease' task: type: string minLength: 1 maxLength: 2000 pattern: \S answers: $ref: '#/components/schemas/IntakeAnswers' materials: type: array items: $ref: '#/components/schemas/IntakeMaterial' maxItems: 64 constraints: $ref: '#/components/schemas/IntakeConstraints' operation: $ref: '#/components/schemas/IntakeOperation' evidence_sets: type: array items: $ref: '#/components/schemas/IntakeEvidenceSet' maxItems: 64 runtime_requirements: $ref: '#/components/schemas/IntakeRuntimeRequirements' artifact_versions: type: array items: $ref: '#/components/schemas/IntakeArtifactVersion' maxItems: 64 evidence_records: type: array items: $ref: '#/components/schemas/IntakeEvidenceRecord' maxItems: 128 required: - schema - decision_id - intake_release - task - answers - materials - constraints - operation additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeConstraints: type: object properties: max_elapsed_seconds: anyOf: - type: integer minimum: 0 maximum: 604800 - type: 'null' max_owner_questions: anyOf: - type: integer minimum: 0 maximum: 1000 - type: 'null' max_model_spend_usd_micros: anyOf: - type: integer minimum: 0 maximum: 1000000000 - type: 'null' source: type: string enum: - user - unknown evidence_refs: $ref: '#/components/schemas/IntakeEvidenceRefs' max_refinement_iterations: anyOf: - type: integer minimum: 0 maximum: 1000 - type: 'null' required: - max_elapsed_seconds - max_owner_questions - max_model_spend_usd_micros - source - evidence_refs additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeStage: type: object properties: id: $ref: '#/components/schemas/IntakeStageId' disposition: type: string enum: - include - defer - omit depth: anyOf: - $ref: '#/components/schemas/IntakeDepth' - type: 'null' suggested_depth: $ref: '#/components/schemas/IntakeDepth' rule_ids: type: array items: type: string pattern: ^R([1-9]|10)$ minItems: 1 reason: type: string minLength: 1 maxLength: 2000 limits: $ref: '#/components/schemas/IntakeLimits' depends_on: type: array items: $ref: '#/components/schemas/IntakeStageId' done_when: type: array items: type: string minLength: 1 maxLength: 1000 minItems: 1 maxItems: 16 reconsider_when: type: array items: type: string minLength: 1 maxLength: 1000 maxItems: 16 requires_confirmation: type: array items: type: string enum: - estimate - model_spend - policy_rulings - import - integration - model_change - external_vendor guidance: $ref: '#/components/schemas/IntakeGuidanceRef' evidence_goal: anyOf: - type: string minLength: 1 maxLength: 2000 - type: 'null' scope: type: array items: $ref: '#/components/schemas/IntakeStageScope' maxItems: 25 required: - id - disposition - depth - suggested_depth - rule_ids - reason - limits - depends_on - done_when - reconsider_when - requires_confirmation - guidance - evidence_goal - scope additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeGap: type: object properties: code: type: string pattern: ^[A-Z][A-Z0-9_]{0,79}$ question_ids: type: array items: $ref: '#/components/schemas/IntakeQuestionId' stage_ids: type: array items: $ref: '#/components/schemas/IntakeStageId' message: type: string minLength: 1 maxLength: 2000 field_paths: type: array items: type: string minLength: 1 maxLength: 256 maxItems: 16 required: - code - question_ids - stage_ids - message additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeSourceUpload: type: object properties: upload_id: $ref: '#/components/schemas/IntakeUploadIdOutput' sha256: $ref: '#/components/schemas/IntakeSha256' required: - upload_id - sha256 additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeAssumption: type: object properties: value: anyOf: - type: boolean - type: string enum: - create - revise - assess - investigate basis: type: string minLength: 1 maxLength: 1000 evidence_refs: type: array items: type: string minLength: 1 maxLength: 512 minItems: 1 maxItems: 8 field_path: type: string minLength: 1 maxLength: 256 required: - value - basis - evidence_refs - field_path additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeEvidenceStatus: type: object properties: record_id: type: string minLength: 1 maxLength: 128 status: type: string enum: - reusable - stale - unverified invalidated_by: type: array items: type: string minLength: 1 maxLength: 128 maxItems: 16 reason: type: string minLength: 1 maxLength: 2000 required: - record_id - status - invalidated_by - reason additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeAnswers: type: object additionalProperties: $ref: '#/components/schemas/IntakeAnswer' IntakeMaterial: type: object properties: id: type: string pattern: ^mat_[A-Za-z0-9_-]{1,64}$ kind: type: string enum: - policy - examples - structure - context location: type: string minLength: 1 maxLength: 512 inspected: type: boolean observations: type: string maxLength: 2000 required: - id - kind - location - inspected additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeOperation: type: object properties: value: anyOf: - type: string enum: - create - type: string enum: - revise - type: string enum: - assess - type: string enum: - investigate - type: - object - 'null' enum: - null - type: 'null' source: type: string enum: - user - inference - unknown evidence_refs: $ref: '#/components/schemas/IntakeEvidenceRefs' note: type: string minLength: 1 maxLength: 1000 required: - value - source - evidence_refs additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeEvidenceSet: type: object properties: id: type: string pattern: ^set_[A-Za-z0-9_-]{1,64}$ material_id: type: string pattern: ^mat_[A-Za-z0-9_-]{1,64}$ fingerprint: anyOf: - type: string minLength: 1 maxLength: 256 - type: 'null' role: type: string enum: - training - assessment - context - unassigned label_source: type: string enum: - human - synthetic - unknown - mixed - unlabeled facts: $ref: '#/components/schemas/IntakeEvidenceFacts' coverage_refs: type: array items: type: string minLength: 1 maxLength: 256 maxItems: 64 membership: anyOf: - $ref: '#/components/schemas/IntakeMembershipRef' - type: 'null' required: - id - material_id - fingerprint - role - label_source - facts - coverage_refs - membership additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeRuntimeRequirements: type: object properties: targets: type: array items: $ref: '#/components/schemas/IntakeRuntimeRequirement' minItems: 1 maxItems: 3 measurement_context: type: string minLength: 1 maxLength: 2000 required: - targets - measurement_context additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeArtifactVersion: type: object properties: id: type: string minLength: 1 maxLength: 128 kind: type: string enum: - brief - structure - objective - input_contract - dataset - model - runtime_requirements fingerprint: type: string minLength: 1 maxLength: 256 required: - id - kind - fingerprint additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeEvidenceRecord: type: object properties: id: type: string minLength: 1 maxLength: 128 stage_id: $ref: '#/components/schemas/IntakeStageId' bindings: type: array items: $ref: '#/components/schemas/IntakeEvidenceBinding' minItems: 1 maxItems: 16 scope: type: array items: $ref: '#/components/schemas/IntakeStageScope' minItems: 1 maxItems: 25 evidence_refs: type: array items: type: string minLength: 1 maxLength: 512 minItems: 1 maxItems: 8 recorded_at: type: string format: date-time required: - id - stage_id - bindings - scope - evidence_refs - recorded_at additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeEvidenceRefs: type: array items: type: string minLength: 1 maxLength: 512 maxItems: 8 IntakeStageId: type: string enum: - objective - case_audit - reconcile - brief - probes - label_check - cases - first_version - baseline - refine - red_team - blind_check - import - integration IntakeDepth: type: string enum: - basic - targeted - extended IntakeLimits: type: object properties: owner_questions: anyOf: - type: integer minimum: 0 maximum: 10000 - type: 'null' synthetic_cases: anyOf: - type: integer minimum: 0 maximum: 10000 - type: 'null' label_checks: anyOf: - type: integer minimum: 0 maximum: 10000 - type: 'null' attack_rounds: anyOf: - type: integer minimum: 0 maximum: 10000 - type: 'null' attack_cases: anyOf: - type: integer minimum: 0 maximum: 10000 - type: 'null' assessment_cases: anyOf: - type: integer minimum: 0 maximum: 10000 - type: 'null' baseline_scorings: anyOf: - type: integer minimum: 0 maximum: 10000 - type: 'null' refinement_iterations: anyOf: - type: integer minimum: 0 maximum: 10000 - type: 'null' required: - owner_questions - synthetic_cases - label_checks - attack_rounds - attack_cases - assessment_cases - baseline_scorings - refinement_iterations additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeGuidanceRef: anyOf: - type: object properties: topic: $ref: '#/components/schemas/IntakeTopic' release: $ref: '#/components/schemas/IntakeRelease' delivery: type: string enum: - skill path: type: string pattern: ^references\/[a-z0-9-]+\.md(#[a-z0-9_-]+)?$ required: - topic - release - delivery - path additionalProperties: true x-moonbounce-sdk-known-fields: true - type: object properties: topic: $ref: '#/components/schemas/IntakeTopic' release: $ref: '#/components/schemas/IntakeRelease' delivery: type: string enum: - mcp required: - topic - release - delivery additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeStageScope: type: string enum: - outcome_tradeoffs - consequential_errors - label_provenance - input_compatibility - coverage_audit - untouched_examples - source_authority - unresolved_policy - policy_clauses - input_contract - fitting_targets - regression_cases - coverage_gaps - clause_mapping - runtime_constraints - baseline_behavior - loss_limitations - supported_repairs - candidate_weaknesses - changed_criteria - action_boundaries - independent_assessment - brief_consistency_only - example_storage - app_integration IntakeQuestionId: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ IntakeUploadIdOutput: type: string pattern: ^upl_[A-Za-z0-9-]{1,80}$ IntakeSha256: type: string pattern: ^[0-9a-f]{64}$ IntakeAnswer: type: object properties: value: anyOf: - type: boolean - type: 'null' source: type: string enum: - user - artifact - server - inference - unknown evidence_refs: $ref: '#/components/schemas/IntakeEvidenceRefs' note: type: string minLength: 1 maxLength: 1000 required: - value - source - evidence_refs additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeEvidenceFacts: type: object properties: labeled: $ref: '#/components/schemas/IntakeAnswer' labels_desired: $ref: '#/components/schemas/IntakeAnswer' labels_reviewed: $ref: '#/components/schemas/IntakeAnswer' examples_compatible: $ref: '#/components/schemas/IntakeAnswer' boundaries_covered: $ref: '#/components/schemas/IntakeAnswer' traffic_sample: $ref: '#/components/schemas/IntakeAnswer' untouched_examples: $ref: '#/components/schemas/IntakeAnswer' additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeMembershipRef: type: object properties: location: type: string minLength: 1 maxLength: 512 sha256: $ref: '#/components/schemas/IntakeSha256' required: - location - sha256 additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeRuntimeRequirement: type: object properties: metric: type: string enum: - mean_cost_usd_micros - p95_latency_ms - loss_per_case maximum: type: number minimum: 0 source: type: string enum: - user evidence_refs: type: array items: type: string minLength: 1 maxLength: 512 minItems: 1 maxItems: 8 required: - metric - maximum - source - evidence_refs additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeEvidenceBinding: type: object properties: artifact_id: type: string minLength: 1 maxLength: 128 fingerprint: type: string minLength: 1 maxLength: 256 required: - artifact_id - fingerprint additionalProperties: true x-moonbounce-sdk-known-fields: true IntakeTopic: type: string pattern: ^(stage|role|procedure)\.[a-z][a-z0-9_.-]{0,100}$ 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.