Getting Started with the Platform

Set up API authentication and make your first call to the Grimoire Platform.

Base URL

https://api.grimoire.run

Authentication

All API requests require an API key. Include it in the x-api-key header or use a Bearer token in the Authorization header:

x-api-key

curl -H "x-api-key: YOUR_API_KEY" https://api.grimoire.run/health

Check Service Health

Verify the API is reachable:

Request

curl https://api.grimoire.run/health

Your First API Call: Validate

The simplest endpoint is /v1/validate. It takes an action plan and checks it against your policies:

Request

curl -X POST https://api.grimoire.run/v1/validate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": "YOUR_PARTNER_ID",
    "action_plan": {
      "chain": "ethereum",
      "actions": [
        {
          "type": "swap",
          "venue": "uniswap_v3",
          "params": {
            "token_in": "USDC",
            "token_out": "ETH",
            "amount_in": "1000"
          }
        }
      ]
    }
  }'

Possible results:

accepted — plan passes all policy checks
rejected — plan violates one or more policies
accepted_with_warnings — plan passes but triggered advisory rules

Response Format

All API responses follow a consistent envelope:

Success

{
  "ok": true,
  "status": "accepted",
  "validation_id": "val_abc123"
}

API Key Scopes

API keys can be scoped to specific capabilities:

Scope	Grants access to
`validate`	`POST /v1/validate`
`run`	`POST /v1/run`
`session:read`	`GET /v1/session/{id}`
`session:write`	`POST /v1/session/{id}`
`policy:read`	`GET` policy endpoints
`policy:write`	`POST`, `PUT` policy endpoints

Next Steps

Validate Actions — full validate endpoint documentation
Run Intents — use natural language to create action plans
Policies — set up automated policy enforcement