{
  "openapi": "3.1.0",
  "info": {
    "title": "Rightshold API",
    "version": "0.1.0",
    "description": "Neutral rights/evidence assessment for agents. Free at launch. Dispositions: ALLOW_WITHIN_POLICY, BLOCK, HUMAN_REVIEW, INSUFFICIENT_EVIDENCE. No trust score."
  },
  "servers": [
    {
      "url": "https://rightshold.com"
    }
  ],
  "paths": {
    "/v1/resources": {
      "get": {
        "operationId": "discover_resources",
        "summary": "List public registry resources",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/assessments": {
      "post": {
        "operationId": "assess_resource_for_use",
        "summary": "Assess a resource for an intended use",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssessRequest"
              }
            }
          }
        }
      }
    },
    "/v1/assessments/premium": {
      "post": {
        "operationId": "assess_premium_deep",
        "summary": "Deep assessment; agent handshake required; 402 in test_paid mode without a settled test-credit receipt",
        "responses": {
          "200": {
            "description": "Assessment"
          },
          "401": {
            "description": "Handshake failed"
          },
          "402": {
            "description": "x402-style payment required (test credits only)"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssessRequest"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "x-agent-id",
            "in": "header",
            "required": true
          },
          {
            "name": "x-timestamp",
            "in": "header",
            "required": true
          },
          {
            "name": "x-nonce",
            "in": "header",
            "required": true
          },
          {
            "name": "x-signature",
            "in": "header",
            "required": true
          },
          {
            "name": "x-payment-receipt",
            "in": "header",
            "required": false
          }
        ]
      }
    },
    "/v1/compare": {
      "post": {
        "operationId": "compare_resource_options",
        "summary": "Compare candidate resources for one intended use",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/v1/evidence/{id}": {
      "get": {
        "operationId": "inspect_evidence",
        "summary": "Tenant-scoped evidence inspection",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true
          },
          {
            "name": "workspace_id",
            "in": "query",
            "required": true
          }
        ]
      }
    },
    "/v1/entitlements/check": {
      "get": {
        "operationId": "check_existing_entitlements",
        "summary": "Existing entitlements for a workspace+resource",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true
          },
          {
            "name": "resource_id",
            "in": "query",
            "required": true
          }
        ]
      }
    },
    "/v1/assessments/check-stale": {
      "post": {
        "operationId": "check_stale_approval",
        "summary": "Material-change (stale approval) check",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/v1/export": {
      "post": {
        "operationId": "export_verification_package",
        "summary": "Export a signed evidence package (tenant-scoped)",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/v1/verify": {
      "post": {
        "operationId": "verify_exported_package",
        "summary": "Verify an exported package",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/v1/agents/register": {
      "post": {
        "operationId": "register_agent",
        "summary": "Register an agent (T0) and receive a T1 key-proof challenge",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "principal_id": {
                    "type": "string"
                  },
                  "operator_org_id": {
                    "type": "string"
                  },
                  "public_key_pem": {
                    "type": "string"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/verify-key": {
      "post": {
        "operationId": "prove_key_control",
        "summary": "T1 challenge-response: sign the challenge with the agent key",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/v1/agents/attest": {
      "post": {
        "operationId": "attest_agent",
        "summary": "T2 operator attestation over agent key + scopes",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/v1/grants": {
      "post": {
        "operationId": "create_delegation_grant",
        "summary": "Scoped, expiring delegation grant with integer micro-unit monetary cap (default 0)",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/v1/payments/settle": {
      "post": {
        "operationId": "settle_test_credits",
        "summary": "TEST-ONLY credit settle with idempotency key (test_paid mode)",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/v1/payments/reconcile": {
      "post": {
        "operationId": "reconcile_payment",
        "summary": "Reconciliation state; unknown outcomes never auto-release",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "operationId": "healthz",
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AssessRequest": {
        "type": "object",
        "required": [
          "resource_id",
          "intended_use"
        ],
        "properties": {
          "principal_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "offer_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "intended_use": {
            "type": "object",
            "properties": {
              "commercial_use": {
                "type": "boolean"
              },
              "redistribution": {
                "type": "boolean"
              },
              "modification": {
                "type": "boolean"
              },
              "sublicensing": {
                "type": "boolean"
              },
              "deployment": {
                "type": "boolean"
              },
              "attribution_planned": {
                "type": "boolean"
              },
              "geography": {
                "type": "string"
              },
              "duration_days": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "model_training": {
                "type": "boolean"
              },
              "model_inference": {
                "type": "boolean"
              }
            }
          }
        }
      }
    }
  },
  "x-rightshold": {
    "dispositions": [
      "ALLOW_WITHIN_POLICY",
      "BLOCK",
      "HUMAN_REVIEW",
      "INSUFFICIENT_EVIDENCE"
    ],
    "handshake": "Ed25519 over canonical {method,path,timestamp,nonce,body_hash}; 5-minute window; nonce single-use",
    "monetization": {
      "mode": "free",
      "launch": "free",
      "premium_micro_units": 10000
    }
  }
}