{
  "openapi": "3.1.0",
  "info": {
    "title": "InferTrail API",
    "version": "v1",
    "description": "Detect abuse of your AI product from request metadata. InferTrail never needs prompt or response content, and rejects requests that include it."
  },
  "servers": [
    {
      "url": "https://api.infertrail.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "secretKey": []
    }
  ],
  "tags": [
    {
      "name": "Scoring",
      "description": "Score each request before you serve it, and record what happened after."
    },
    {
      "name": "Batch ingestion",
      "description": "Send usage and identity events in batches from your backend, and check their processing."
    },
    {
      "name": "Accounts",
      "description": "Read scores, labels and usage for your accounts."
    },
    {
      "name": "Signups",
      "description": "Score new signups and record what they turned out to be."
    },
    {
      "name": "Browser sensor",
      "description": "Collect browser signals with a publishable key and verify them from your backend."
    }
  ],
  "paths": {
    "/v1/score": {
      "post": {
        "tags": [
          "Scoring"
        ],
        "operationId": "score",
        "summary": "Score a request",
        "description": "Call before you serve a model request. Returns a risk score and whether to refuse the request. The answer comes from InferTrail's edge, typically within milliseconds. If scoring itself fails you still get HTTP 200 with score 0 and the reason `scoring_unavailable`, so a failure never blocks your users; blocks and spend caps still apply.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScoreRequest"
              },
              "example": {
                "account_id": "acct_42",
                "event_id": "req_8f3a",
                "session_id": "sess_19",
                "account": {
                  "subscription_tier": "pro",
                  "first_seen": "2026-10-02T09:15:00Z",
                  "context": {
                    "plan_type": "paid",
                    "email_verified": true
                  }
                },
                "request": {
                  "ip": "203.0.113.7",
                  "user_agent": "Mozilla/5.0",
                  "model_requested": "gpt-4o-mini",
                  "estimated_prompt_tokens": 850
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The score.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScoreResponse"
                },
                "example": {
                  "event_id": "req_8f3a",
                  "score": 0.12,
                  "tier": "low",
                  "reasons": [],
                  "blocked": false,
                  "shadow_mode": false,
                  "baseline_ready": true,
                  "deep_mode_active": false,
                  "signals_fused": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/events/post-call": {
      "post": {
        "tags": [
          "Scoring"
        ],
        "operationId": "postCall",
        "summary": "Record a completed call",
        "description": "Call after a model request finishes, with its usage and cost. The event is queued durably before the answer; pricing, spend totals and caps are applied right after. Unknown token counts stay unknown rather than counting as zero.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PostCallRequest"
              },
              "example": {
                "account_id": "acct_42",
                "event_id": "req_8f3a",
                "model": "gpt-4o-mini",
                "prompt_tokens": 850,
                "completion_tokens": 212,
                "latency_ms": 1430,
                "inference_cost_usd": 0.00026
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted for processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Accepted"
                },
                "example": {
                  "ok": true,
                  "accepted": true,
                  "event_id": "req_8f3a"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/identity": {
      "post": {
        "tags": [
          "Scoring"
        ],
        "operationId": "identity",
        "summary": "Record an identity event",
        "description": "Record a login, signup or similar event for an account, so its network and device history inform later scores.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IdentityRequest"
              },
              "example": {
                "account_id": "acct_42",
                "event_id": "login_771",
                "event_type": "login",
                "ip": "203.0.113.7",
                "user_agent": "Mozilla/5.0"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recorded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recorded"
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/labels": {
      "post": {
        "tags": [
          "Scoring"
        ],
        "operationId": "label",
        "summary": "Label an account",
        "description": "Tell InferTrail what an account turned out to be. Labels are your ground truth: they show in the dashboard and carry over to signups linked to the account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "account_id": {
                    "type": "string",
                    "description": "The account to label.",
                    "pattern": "\\S"
                  },
                  "label": {
                    "type": "string",
                    "description": "Your verdict.",
                    "enum": [
                      "fraud",
                      "legitimate"
                    ]
                  },
                  "notes": {
                    "type": "string",
                    "description": "Free-text notes for your team. Do not include personal data you don't need."
                  },
                  "event_id": {
                    "type": "string",
                    "description": "Your idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event.",
                    "maxLength": 256
                  }
                },
                "required": [
                  "account_id",
                  "label"
                ]
              },
              "example": {
                "account_id": "acct_42",
                "label": "fraud",
                "event_id": "label_acct_42_1"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recorded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recorded"
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/accounts/{account_id}/context": {
      "post": {
        "tags": [
          "Scoring"
        ],
        "operationId": "accountContext",
        "summary": "Set account context",
        "description": "Store facts about an account, such as its plan or whether its email is verified, without sending them on every score. Facts you send inline with `POST /v1/score` overlay these.",
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "Your identifier for the end user's account, URL-encoded.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountContext"
              },
              "example": {
                "plan_type": "trial",
                "has_payment_method": false,
                "email_verified": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recorded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recorded"
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/ingress/events": {
      "post": {
        "tags": [
          "Batch ingestion"
        ],
        "operationId": "ingest",
        "summary": "Send events in a batch",
        "description": "Send 1 to 100 post-call or identity events in one request from your backend. HTTP 202 means every event is durably queued, not yet processed; each gets a receipt you can check. If the answer is 503, resend the same batch with the same event IDs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "events": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/IngressEvent"
                    },
                    "description": "1 to 100 events.",
                    "minItems": 1,
                    "maxItems": 100
                  }
                },
                "required": [
                  "events"
                ]
              },
              "example": {
                "events": [
                  {
                    "event_id": "call_1001",
                    "type": "post_call",
                    "data": {
                      "account_id": "acct_42",
                      "model": "gpt-4o-mini",
                      "prompt_tokens": 100,
                      "completion_tokens": 50,
                      "inference_cost_usd": 4e-05
                    }
                  },
                  {
                    "event_id": "login_772",
                    "type": "identity",
                    "event_time": "2026-11-18T08:00:00Z",
                    "data": {
                      "account_id": "acct_42",
                      "event_type": "login",
                      "ip": "203.0.113.7"
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "acceptance": {
                      "type": "string",
                      "description": "Always `queue`."
                    },
                    "accepted": {
                      "type": "integer",
                      "description": "Number of events queued."
                    },
                    "processing": {
                      "type": "string",
                      "description": "Always `asynchronous`."
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "event_id": {
                            "type": "string",
                            "description": "The event's ID."
                          },
                          "receipt_id": {
                            "type": "string",
                            "description": "The receipt to check."
                          },
                          "status": {
                            "type": "string",
                            "description": "Always `queued`."
                          },
                          "status_url": {
                            "type": "string",
                            "description": "Path of the receipt."
                          }
                        }
                      },
                      "description": "One receipt per event, in request order."
                    }
                  }
                },
                "example": {
                  "acceptance": "queue",
                  "accepted": 1,
                  "processing": "asynchronous",
                  "events": [
                    {
                      "event_id": "call_1001",
                      "receipt_id": "rcpt_5c1d",
                      "status": "queued",
                      "status_url": "/v1/ingress/receipts/rcpt_5c1d"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/ingress/receipts/{receipt_id}": {
      "get": {
        "tags": [
          "Batch ingestion"
        ],
        "operationId": "receipt",
        "summary": "Check a receipt",
        "description": "How a queued event is doing. A brand-new receipt can return 404 for a moment until processing records it.",
        "parameters": [
          {
            "name": "receipt_id",
            "in": "path",
            "required": true,
            "description": "The `receipt_id` from the batch answer.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The receipt.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                },
                "example": {
                  "receipt_id": "rcpt_5c1d",
                  "event_id": "call_1001",
                  "type": "post_call",
                  "status": "completed",
                  "completed_at": "2026-11-18T08:00:01Z"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "504": {
            "$ref": "#/components/responses/Timeout"
          }
        }
      }
    },
    "/v1/ingress/events/{event_id}": {
      "get": {
        "tags": [
          "Batch ingestion"
        ],
        "operationId": "ingressEvent",
        "summary": "Check an event",
        "description": "The same status as a receipt, found by your event ID.",
        "parameters": [
          {
            "name": "event_id",
            "in": "path",
            "required": true,
            "description": "Your event ID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The event's status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "504": {
            "$ref": "#/components/responses/Timeout"
          }
        }
      }
    },
    "/v1/ingress/status": {
      "get": {
        "tags": [
          "Batch ingestion"
        ],
        "operationId": "ingressStatus",
        "summary": "Ingestion health",
        "description": "Counts of your recently processed events by outcome, and the latest ones.",
        "responses": {
          "200": {
            "description": "Recent outcomes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "window_seconds": {
                      "type": "integer",
                      "description": "How far back the counts reach."
                    },
                    "counts": {
                      "type": "object",
                      "properties": {
                        "completed": {
                          "type": "integer",
                          "description": "Processed."
                        },
                        "conflict": {
                          "type": "integer",
                          "description": "Rejected for reusing an event ID with different data."
                        },
                        "failed": {
                          "type": "integer",
                          "description": "Failed after retries."
                        }
                      }
                    },
                    "recent": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Receipt"
                      },
                      "description": "The latest events."
                    }
                  },
                  "required": [
                    "window_seconds",
                    "counts",
                    "recent"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "504": {
            "$ref": "#/components/responses/Timeout"
          }
        }
      }
    },
    "/v1/accounts": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "operationId": "listAccounts",
        "summary": "List accounts",
        "description": "Your accounts with their latest score, label and spend, one page at a time.",
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "What to sort by.",
            "schema": {
              "type": "string",
              "enum": [
                "score",
                "last_seen",
                "first_seen",
                "requests",
                "spend"
              ],
              "default": "score"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "Sort direction.",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          {
            "name": "label",
            "in": "query",
            "required": false,
            "description": "Only accounts with this label.",
            "schema": {
              "type": "string",
              "enum": [
                "fraud",
                "legitimate",
                "unlabeled"
              ]
            }
          },
          {
            "name": "tier",
            "in": "query",
            "required": false,
            "description": "Only accounts whose latest tier is this.",
            "schema": {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high"
              ]
            }
          },
          {
            "name": "min_score",
            "in": "query",
            "required": false,
            "description": "Only accounts whose latest score is at least this.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          {
            "name": "window",
            "in": "query",
            "required": false,
            "description": "How far back usage totals reach, counted from the start of the current hour.",
            "schema": {
              "type": "string",
              "enum": [
                "1h",
                "1d",
                "7d",
                "30d"
              ],
              "default": "30d"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Values above 200 are capped at 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Number of entries to skip.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of accounts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accounts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AccountSummary"
                      },
                      "description": "The page."
                    },
                    "total": {
                      "type": "integer",
                      "description": "Accounts matching the filters."
                    },
                    "limit": {
                      "type": "integer",
                      "description": "The page size used."
                    },
                    "offset": {
                      "type": "integer",
                      "description": "The offset used."
                    }
                  },
                  "required": [
                    "accounts",
                    "total",
                    "limit",
                    "offset"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/accounts/{account_id}": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "operationId": "getAccount",
        "summary": "Get an account",
        "description": "One account's latest score and its usage in the window, including which models it used.",
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "Your identifier for the end user's account, URL-encoded.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "window",
            "in": "query",
            "required": false,
            "description": "How far back usage totals reach, counted from the start of the current hour.",
            "schema": {
              "type": "string",
              "enum": [
                "1h",
                "1d",
                "7d",
                "30d"
              ],
              "default": "30d"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The account.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account_id": {
                      "type": "string",
                      "description": "Your account identifier."
                    },
                    "first_seen": {
                      "type": "string",
                      "description": "When InferTrail first saw the account."
                    },
                    "last_seen": {
                      "type": "string",
                      "description": "When it was last active."
                    },
                    "subscription_tier": {
                      "type": "string",
                      "description": "The subscription tier you reported."
                    },
                    "request_count": {
                      "type": "integer",
                      "description": "Scored requests."
                    },
                    "latest_score": {
                      "type": "object",
                      "properties": {
                        "score": {
                          "type": "number",
                          "description": "The score."
                        },
                        "tier": {
                          "type": "string",
                          "enum": [
                            "low",
                            "medium",
                            "high"
                          ],
                          "description": "Risk band of the score: below 0.4 is low, 0.4 up to 0.7 is medium, 0.7 and above is high."
                        },
                        "reasons": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          },
                          "description": "Its reasons."
                        },
                        "received_at": {
                          "type": "string",
                          "description": "When it was given."
                        },
                        "shadow_mode": {
                          "type": "boolean",
                          "description": "Whether it came from cold-start rules."
                        },
                        "deep_mode_active": {
                          "type": "boolean",
                          "description": "Always false."
                        }
                      },
                      "required": [
                        "score",
                        "tier",
                        "reasons",
                        "received_at",
                        "shadow_mode",
                        "deep_mode_active"
                      ]
                    },
                    "window": {
                      "type": "object",
                      "properties": {
                        "events": {
                          "type": "integer",
                          "description": "Completed calls."
                        },
                        "prompt_tokens": {
                          "type": "integer",
                          "description": "Prompt tokens."
                        },
                        "completion_tokens": {
                          "type": "integer",
                          "description": "Completion tokens."
                        },
                        "inference_cost_usd": {
                          "type": "number",
                          "description": "Spend in US dollars."
                        }
                      },
                      "required": [
                        "events",
                        "prompt_tokens",
                        "completion_tokens",
                        "inference_cost_usd"
                      ],
                      "description": "Usage in the window."
                    },
                    "model_mix": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "model": {
                            "type": "string",
                            "description": "Model name."
                          },
                          "count": {
                            "type": "integer",
                            "description": "Calls."
                          }
                        },
                        "required": [
                          "model",
                          "count"
                        ]
                      },
                      "description": "Calls per model in the window."
                    }
                  },
                  "required": [
                    "account_id",
                    "first_seen",
                    "last_seen",
                    "subscription_tier",
                    "request_count",
                    "latest_score",
                    "window",
                    "model_mix"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/accounts/{account_id}/scores": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "operationId": "accountScores",
        "summary": "List an account's scores",
        "description": "The account's score history, newest first.",
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "Your identifier for the end user's account, URL-encoded.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Values above 200 are capped at 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Number of entries to skip.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of scores.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scores": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "description": "A stable numeric ID for this entry."
                          },
                          "session_id": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The session you reported."
                          },
                          "received_at": {
                            "type": "string",
                            "description": "When the request was scored."
                          },
                          "ip": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "A keyed hash of the IP address, never the address itself."
                          },
                          "model_requested": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The model requested."
                          },
                          "estimated_prompt_tokens": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "The estimate you sent."
                          },
                          "score": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "The score."
                          },
                          "tier": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "enum": [
                              "low",
                              "medium",
                              "high",
                              null
                            ],
                            "description": "The tier."
                          },
                          "reasons": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "string"
                            },
                            "description": "The reasons."
                          },
                          "shadow_mode": {
                            "type": "boolean",
                            "description": "Whether cold-start rules produced it."
                          },
                          "deep_mode_active": {
                            "type": "boolean",
                            "description": "Always false."
                          }
                        },
                        "required": [
                          "id",
                          "session_id",
                          "received_at",
                          "ip",
                          "model_requested",
                          "estimated_prompt_tokens",
                          "score",
                          "tier",
                          "reasons",
                          "shadow_mode",
                          "deep_mode_active"
                        ]
                      },
                      "description": "The page."
                    },
                    "total": {
                      "type": "integer",
                      "description": "All scores for the account."
                    },
                    "limit": {
                      "type": "integer",
                      "description": "The page size used."
                    },
                    "offset": {
                      "type": "integer",
                      "description": "The offset used."
                    }
                  },
                  "required": [
                    "scores",
                    "total",
                    "limit",
                    "offset"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "operationId": "stats",
        "summary": "Workspace totals",
        "description": "Account counts by latest tier and label, and activity in the last 24 hours.",
        "responses": {
          "200": {
            "description": "Totals.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_accounts": {
                      "type": "integer",
                      "description": "All accounts."
                    },
                    "high_risk_accounts": {
                      "type": "integer",
                      "description": "Accounts whose latest tier is high."
                    },
                    "medium_risk_accounts": {
                      "type": "integer",
                      "description": "Latest tier medium."
                    },
                    "low_risk_accounts": {
                      "type": "integer",
                      "description": "Latest tier low."
                    },
                    "unscored_accounts": {
                      "type": "integer",
                      "description": "Never scored."
                    },
                    "labeled_fraud": {
                      "type": "integer",
                      "description": "Labelled fraud."
                    },
                    "labeled_legitimate": {
                      "type": "integer",
                      "description": "Labelled legitimate."
                    },
                    "unlabeled": {
                      "type": "integer",
                      "description": "Without a label."
                    },
                    "scores_24h": {
                      "type": "integer",
                      "description": "Scores in the last 24 hours."
                    },
                    "events_24h": {
                      "type": "integer",
                      "description": "Completed calls recorded in the last 24 hours."
                    }
                  },
                  "required": [
                    "total_accounts",
                    "high_risk_accounts",
                    "medium_risk_accounts",
                    "low_risk_accounts",
                    "unscored_accounts",
                    "labeled_fraud",
                    "labeled_legitimate",
                    "unlabeled",
                    "scores_24h",
                    "events_24h"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/integration/status": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "operationId": "integrationStatus",
        "summary": "Check your integration",
        "description": "Which fields your calls actually send, how often, and which detections are unavailable because a signal is missing.",
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "required": false,
            "description": "Period to inspect.",
            "schema": {
              "type": "string",
              "enum": [
                "1h",
                "24h",
                "7d",
                "30d"
              ],
              "default": "7d"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Coverage of your signals.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "window": {
                      "type": "string",
                      "description": "The period inspected."
                    },
                    "estimated": {
                      "type": "boolean",
                      "description": "Whether the counts are estimates."
                    },
                    "detections_unavailable": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Detections that need a signal you don't send."
                    },
                    "payloads": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "endpoint": {
                            "type": "string",
                            "description": "The endpoint."
                          },
                          "calls": {
                            "type": "integer",
                            "description": "Calls in the period."
                          },
                          "signals": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "path": {
                                  "type": "string",
                                  "description": "Field path in the request."
                                },
                                "tier": {
                                  "type": "string",
                                  "description": "How much it matters.",
                                  "enum": [
                                    "required",
                                    "high_yield",
                                    "optional"
                                  ]
                                },
                                "present": {
                                  "type": [
                                    "number",
                                    "null"
                                  ],
                                  "description": "Share of calls that sent it, from 0 to 1."
                                },
                                "detects": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  },
                                  "description": "What it helps detect."
                                },
                                "sends_prompt_content": {
                                  "type": "boolean",
                                  "description": "Always false."
                                },
                                "description": {
                                  "type": "string",
                                  "description": "What the field is."
                                },
                                "note": {
                                  "type": "string",
                                  "description": "Advice on sending it."
                                }
                              }
                            },
                            "description": "Per-field coverage."
                          }
                        }
                      },
                      "description": "Per endpoint."
                    }
                  },
                  "required": [
                    "window",
                    "estimated",
                    "detections_unavailable",
                    "payloads"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/registrations/score": {
      "post": {
        "tags": [
          "Signups"
        ],
        "operationId": "scoreSignup",
        "summary": "Score a signup",
        "description": "Score a new signup before you create the account. Keep the returned `registration_id` and pass it to `POST /v1/identity` once the account exists, to link the two.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "The email address the user signed up with."
                  },
                  "event_id": {
                    "type": "string",
                    "description": "Your idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event.",
                    "maxLength": 256
                  },
                  "ip": {
                    "type": "string",
                    "description": "The user's IP address."
                  },
                  "ip_hash": {
                    "type": "string",
                    "description": "Your hash of the IP address, used when `ip` is absent."
                  },
                  "asn": {
                    "type": "integer",
                    "description": "Autonomous system number."
                  },
                  "ip_country": {
                    "type": "string",
                    "description": "Country of the IP address."
                  },
                  "declared_country": {
                    "type": "string",
                    "description": "The country the user entered."
                  },
                  "user_agent": {
                    "type": "string",
                    "description": "The User-Agent header."
                  },
                  "device_fingerprint": {
                    "type": "string",
                    "description": "Your device fingerprint."
                  },
                  "sensor_token": {
                    "type": "string",
                    "description": "A browser sensor token."
                  },
                  "client": {
                    "type": "object",
                    "properties": {
                      "webdriver": {
                        "type": "boolean",
                        "description": "`navigator.webdriver`."
                      },
                      "fingerprint_anomaly": {
                        "type": "number",
                        "description": "Your fingerprint anomaly score."
                      },
                      "load_to_submit_ms": {
                        "type": "number",
                        "description": "Time from page load to submit."
                      },
                      "timezone": {
                        "type": "string",
                        "description": "The browser's time zone."
                      }
                    },
                    "description": "Browser signals."
                  },
                  "form": {
                    "type": "object",
                    "properties": {
                      "load_to_submit_ms": {
                        "type": "number",
                        "description": "Time from form display to submit."
                      },
                      "fields": {
                        "type": "object",
                        "description": "Per-field interaction metadata. Never field values."
                      }
                    },
                    "description": "Form interaction timing."
                  },
                  "phone": {
                    "type": "string",
                    "description": "The phone number entered."
                  },
                  "username": {
                    "type": "string",
                    "description": "The username chosen."
                  },
                  "referrer": {
                    "type": "string",
                    "description": "The referring page."
                  },
                  "deadline_ms": {
                    "type": "integer",
                    "description": "How long you can wait for an answer, in milliseconds."
                  }
                },
                "required": [
                  "email"
                ]
              },
              "example": {
                "email": "new.user@example.com",
                "event_id": "signup_9001",
                "ip": "198.51.100.23",
                "user_agent": "Mozilla/5.0",
                "declared_country": "US"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The signup's score.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "registration_id": {
                      "type": "string",
                      "description": "Keep this to link the signup to its account."
                    },
                    "tier": {
                      "type": "integer",
                      "description": "Risk level as a number."
                    },
                    "score": {
                      "type": "number",
                      "description": "Risk from 0 to 1."
                    },
                    "reasons": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Machine-readable reasons."
                    },
                    "duplicate": {
                      "type": "boolean",
                      "description": "True when this `event_id` was already scored."
                    },
                    "shadow_mode": {
                      "type": "boolean",
                      "description": "Whether the score is observe-only."
                    },
                    "degraded": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Signals that could not be checked in time."
                    }
                  },
                  "required": [
                    "registration_id",
                    "tier",
                    "score",
                    "reasons"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/registrations/{registration_id}/label": {
      "post": {
        "tags": [
          "Signups"
        ],
        "operationId": "labelSignup",
        "summary": "Label a signup",
        "description": "Record what a signup turned out to be. Send an `Idempotency-Key` header so a retry is not applied twice.",
        "parameters": [
          {
            "name": "registration_id",
            "in": "path",
            "required": true,
            "description": "The `registration_id` from the signup's score.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Your key for this label request; send exactly one.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "Your verdict.",
                    "enum": [
                      "fraud",
                      "legitimate"
                    ]
                  }
                },
                "required": [
                  "label"
                ]
              },
              "example": {
                "label": "legitimate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recorded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accepted": {
                      "type": "boolean",
                      "description": "Always true on success."
                    }
                  },
                  "required": [
                    "accepted"
                  ]
                },
                "example": {
                  "accepted": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "504": {
            "$ref": "#/components/responses/Timeout"
          }
        }
      }
    },
    "/v1/sensor/collect": {
      "post": {
        "tags": [
          "Browser sensor"
        ],
        "operationId": "sensorCollect",
        "summary": "Collect browser signals",
        "description": "Called from the browser with your publishable key (`pk_live_…`) in `siteKey`, not a secret key. Returns a short-lived signed token; pass it to your backend and on to `POST /v1/score` as `request.sensor_token` or to `POST /v1/sensor/verify`. The request must come from an origin you allowed for that key.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "siteKey": {
                    "type": "string",
                    "description": "Your publishable key."
                  },
                  "v": {
                    "type": "integer",
                    "description": "Payload version."
                  },
                  "sessionId": {
                    "type": "string",
                    "description": "Your session identifier."
                  },
                  "action": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "What the user is doing, such as `login`."
                  },
                  "fingerprint": {
                    "type": "string",
                    "description": "A device fingerprint."
                  },
                  "loadedEpoch": {
                    "type": "integer",
                    "description": "When the page loaded, in Unix milliseconds."
                  },
                  "collectedAtMs": {
                    "type": "integer",
                    "description": "When signals were collected."
                  },
                  "url": {
                    "type": "string",
                    "description": "The page URL."
                  },
                  "referrer": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The referring page."
                  },
                  "environment": {
                    "type": "object",
                    "description": "Browser environment: user agent, languages, platform, hardware, time zone, canvas and WebGL identifiers."
                  },
                  "automation": {
                    "type": "object",
                    "description": "Automation indicators, such as `webdriver` and known headless traits."
                  },
                  "behavior": {
                    "type": "object",
                    "description": "Interaction counts: mouse movement, clicks, keys, scrolls and touches."
                  }
                },
                "required": [
                  "siteKey"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A signed token and an early decision.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Valid for two minutes."
                    },
                    "decision": {
                      "type": "string",
                      "description": "Early read on the browser.",
                      "enum": [
                        "allow",
                        "challenge",
                        "deny"
                      ]
                    }
                  },
                  "required": [
                    "token",
                    "decision"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/sensor/verify": {
      "post": {
        "tags": [
          "Browser sensor"
        ],
        "operationId": "sensorVerify",
        "summary": "Verify a sensor token",
        "description": "From your backend, with your secret key: check a token from `POST /v1/sensor/collect` and get the browser's verdict.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "The token from collect."
                  },
                  "action": {
                    "type": "string",
                    "description": "The action you expect, if you set one at collect."
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The browser's verdict.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "is_bot": {
                      "type": "boolean",
                      "description": "Whether the browser looks automated."
                    },
                    "is_human": {
                      "type": "boolean",
                      "description": "Whether it looks human."
                    },
                    "score": {
                      "type": "number",
                      "description": "Bot likelihood from 0 to 1."
                    },
                    "decision": {
                      "type": "string",
                      "description": "What to do.",
                      "enum": [
                        "allow",
                        "challenge",
                        "deny"
                      ]
                    },
                    "reasons": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Why."
                    }
                  },
                  "required": [
                    "is_bot",
                    "is_human",
                    "score",
                    "decision",
                    "reasons"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "secretKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your secret API key, which starts with `it_live_`. Send `Authorization: Bearer it_live_…` from your backend only; never put a secret key in a browser or app."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "A short, human-readable reason. Never contains your key or payload."
          }
        },
        "required": [
          "error"
        ]
      },
      "AccountContext": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "plan_type": {
            "type": [
              "string",
              "null"
            ],
            "description": "The account's plan. Recognized values: `paid`, `unpaid`, `trial`, `free` (any case). Other values are ignored."
          },
          "has_payment_method": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether a payment method is on file."
          },
          "email_verified": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the account's email address is verified."
          },
          "identity_verified": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether you have verified the account holder's identity."
          },
          "prior_chargeback": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the account has had a chargeback."
          },
          "billing_delinquent": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the account is behind on payments."
          },
          "trust_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your trust assertion. Recognized values: `vip`, `allowlisted`, `allowlist`, `trusted` (any case)."
          }
        },
        "description": "Facts you attest about the account. A null, empty or unrecognized value changes nothing; recognized values overlay what InferTrail already stores."
      },
      "ScoreRequest": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string",
            "description": "Your identifier for the end user's account. Required and not blank.",
            "pattern": "\\S"
          },
          "event_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event.",
            "maxLength": 256
          },
          "session_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your identifier for the user's session, if you have one."
          },
          "account": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "subscription_tier": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Your name for the account's subscription tier."
              },
              "first_seen": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "When the account was created, as an RFC 3339 timestamp with a time zone.",
                "format": "date-time"
              },
              "context": {
                "$ref": "#/components/schemas/AccountContext"
              }
            },
            "description": "What you know about the account. Only these three keys are accepted."
          },
          "request": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "ip": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The end user's IP address."
              },
              "ip_hash": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Your own hash of the end user's IP address, used only when `ip` is absent. At most 128 characters."
              },
              "asn": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "The autonomous system number of the end user's network.",
                "minimum": 0,
                "maximum": 4294967295
              },
              "ip_country": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Two-letter country code of the end user's IP address. Malformed values are dropped."
              },
              "user_agent": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The end user's User-Agent header."
              },
              "model_requested": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The model the user asked for."
              },
              "estimated_prompt_tokens": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Your estimate of the prompt's size in tokens."
              },
              "sensor_token": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A token from `POST /v1/sensor/collect`. Accepted, but not yet used in the score; see `signals_fused`."
              },
              "session_signals": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "ms_since_last_request": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Milliseconds since this session's previous request."
                  },
                  "ms_since_page_load": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Milliseconds since the page that sent the request loaded."
                  },
                  "interaction_events_count": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Number of user interactions (clicks, keys, scrolls) seen in the session."
                  },
                  "ms_since_signup": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Milliseconds since the account signed up."
                  },
                  "is_first_request_in_session": {
                    "type": [
                      "boolean",
                      "null"
                    ],
                    "description": "Whether this is the session's first request."
                  }
                },
                "description": "Behavioral timing you observed in the session."
              },
              "client": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "webdriver": {
                    "type": [
                      "boolean",
                      "null"
                    ],
                    "description": "Whether the browser reported `navigator.webdriver`."
                  }
                },
                "description": "Client-side automation signals."
              }
            },
            "description": "Metadata about this request. Never include prompt or response text."
          }
        },
        "required": [
          "account_id"
        ]
      },
      "ScoreResponse": {
        "type": "object",
        "properties": {
          "event_id": {
            "type": "string",
            "description": "The event's ID: yours, or one InferTrail generated when you sent none."
          },
          "score": {
            "type": "number",
            "description": "Risk from 0 (benign) to 1 (abusive).",
            "minimum": 0,
            "maximum": 1
          },
          "tier": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "description": "Risk band of the score: below 0.4 is low, 0.4 up to 0.7 is medium, 0.7 and above is high."
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Machine-readable reasons, most important first. `scoring_unavailable` means scoring failed and the answer is a safe default."
          },
          "blocked": {
            "type": "boolean",
            "description": "Whether you should refuse the request: a manual block or an exceeded spend cap applies."
          },
          "shadow_mode": {
            "type": "boolean",
            "description": "True while the account has too little history for the trained model; the score then comes from cold-start rules."
          },
          "baseline_ready": {
            "type": "boolean",
            "description": "True once the account's history is sufficient for the trained model."
          },
          "deep_mode_active": {
            "type": "boolean",
            "description": "Always false. InferTrail never inspects prompt content."
          },
          "signals_fused": {
            "type": "boolean",
            "description": "Currently always false: browser sensor signals are not yet combined into scores. Check a sensor token with `POST /v1/sensor/verify`."
          },
          "duplicate": {
            "type": "boolean",
            "description": "Present and true when this `event_id` was already scored; the original answer is returned unchanged."
          },
          "algorithm": {
            "type": "string",
            "description": "Name of the scoring method that produced the score."
          },
          "algorithm_version": {
            "type": "string",
            "description": "Version of that method."
          },
          "service_version": {
            "type": "string",
            "description": "Version of the scoring service."
          },
          "scorer_version": {
            "type": "string",
            "description": "Version of the full scorer, including its rules."
          },
          "grouping": {
            "type": "object",
            "description": "Evidence from your workspace's group rules, when any matched. See your dashboard's scoring settings."
          }
        },
        "required": [
          "score",
          "tier",
          "reasons",
          "blocked",
          "shadow_mode",
          "baseline_ready",
          "deep_mode_active",
          "signals_fused"
        ]
      },
      "Telemetry": {
        "type": "object",
        "properties": {
          "version": {
            "type": "integer",
            "description": "1, or 2 to include `model_id` and `stream`.",
            "enum": [
              1,
              2
            ]
          },
          "source_id": {
            "type": "string",
            "description": "Your identifier for the system that served the call, at most 128 bytes."
          },
          "model_family": {
            "type": "string",
            "description": "Size class of the model.",
            "enum": [
              "small",
              "medium",
              "large",
              "reasoning"
            ]
          },
          "model_id": {
            "type": "string",
            "description": "Version 2 only: the exact model identifier, at most 256 bytes."
          },
          "stream": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Version 2 only: whether the response was streamed."
          },
          "status": {
            "type": "integer",
            "description": "HTTP status your model call returned.",
            "minimum": 100,
            "maximum": 599
          },
          "start_ts": {
            "type": "number",
            "description": "When the call started, in Unix seconds.",
            "minimum": 0
          },
          "end_ts": {
            "type": "number",
            "description": "When the call ended, in Unix seconds: not before `start_ts`, at most a day after it and not in the future."
          }
        },
        "required": [
          "version",
          "source_id",
          "model_family",
          "status",
          "start_ts",
          "end_ts"
        ],
        "description": "Timing of the completed model call."
      },
      "PostCallRequest": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string",
            "description": "The account that made the call. Required and not blank.",
            "pattern": "\\S"
          },
          "event_id": {
            "type": "string",
            "description": "Your idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event.",
            "maxLength": 256
          },
          "session_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your identifier for the user's session."
          },
          "model": {
            "type": [
              "string",
              "null"
            ],
            "description": "The model that served the call."
          },
          "prompt_tokens": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Prompt tokens used. Null or absent means unknown, not zero.",
            "minimum": 0
          },
          "completion_tokens": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Completion tokens used. Null or absent means unknown, not zero.",
            "minimum": 0
          },
          "latency_ms": {
            "type": [
              "integer",
              "null"
            ],
            "description": "How long the call took, in milliseconds.",
            "minimum": 0
          },
          "inference_cost_usd": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "What the call cost you, in US dollars. When omitted, InferTrail estimates it from tokens and marks the estimate."
          },
          "telemetry": {
            "$ref": "#/components/schemas/Telemetry"
          }
        },
        "required": [
          "account_id"
        ]
      },
      "Accepted": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on success."
          },
          "accepted": {
            "type": "boolean",
            "description": "The event is durably queued. Pricing and spend caps are applied after the answer."
          },
          "event_id": {
            "type": "string",
            "description": "The event's ID: yours, or one InferTrail generated."
          }
        },
        "required": [
          "ok",
          "accepted",
          "event_id"
        ]
      },
      "Recorded": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on success."
          },
          "duplicate": {
            "type": "boolean",
            "description": "Present and true when this `event_id` was already recorded."
          }
        },
        "required": [
          "ok"
        ]
      },
      "IdentityRequest": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string",
            "description": "The account the identity event belongs to.",
            "pattern": "\\S"
          },
          "event_id": {
            "type": "string",
            "description": "Your idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event.",
            "maxLength": 256
          },
          "session_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your identifier for the user's session."
          },
          "event_type": {
            "type": [
              "string",
              "null"
            ],
            "description": "What happened, such as `login`, `signup` or `password_reset`."
          },
          "ip": {
            "type": [
              "string",
              "null"
            ],
            "description": "The user's IP address."
          },
          "ip_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your own hash of the IP address, used only when `ip` is absent."
          },
          "asn": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Autonomous system number of the user's network.",
            "minimum": 0,
            "maximum": 4294967295
          },
          "ip_country": {
            "type": [
              "string",
              "null"
            ],
            "description": "Two-letter country code of the IP address."
          },
          "user_agent": {
            "type": [
              "string",
              "null"
            ],
            "description": "The user's User-Agent header."
          },
          "registration_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The `registration_id` from `POST /v1/registrations/score`, to link the signup to this account."
          }
        },
        "required": [
          "account_id"
        ]
      },
      "IngressEvent": {
        "type": "object",
        "properties": {
          "event_id": {
            "type": "string",
            "description": "Required idempotency key, at most 256 characters, unique within the request.",
            "maxLength": 256
          },
          "type": {
            "type": "string",
            "description": "The event's kind.",
            "enum": [
              "post_call",
              "identity"
            ]
          },
          "event_time": {
            "type": "string",
            "description": "When the event happened, at most seven days ago and one minute ahead. Defaults to the time InferTrail received it.",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "description": "The event: the fields of `POST /v1/events/post-call` for `post_call`, or of `POST /v1/identity` for `identity`. A `data.event_id`, if sent, must equal the envelope's."
          }
        },
        "required": [
          "event_id",
          "type",
          "data"
        ]
      },
      "Receipt": {
        "type": "object",
        "properties": {
          "receipt_id": {
            "type": "string",
            "description": "The receipt's ID."
          },
          "event_id": {
            "type": "string",
            "description": "The event's ID."
          },
          "type": {
            "type": "string",
            "description": "The event's kind."
          },
          "event_time": {
            "type": "string",
            "description": "When the event happened."
          },
          "received_at": {
            "type": "string",
            "description": "When InferTrail received it."
          },
          "status": {
            "type": "string",
            "description": "`queued` while waiting, `completed` once processed, `conflict` if the event ID was reused with different data (the original is kept), or `failed` after the queue's retries ran out.",
            "enum": [
              "queued",
              "completed",
              "conflict",
              "failed"
            ]
          },
          "completed_at": {
            "type": "string",
            "description": "When processing finished."
          },
          "error": {
            "type": "string",
            "description": "Why processing did not complete."
          }
        },
        "required": [
          "status"
        ]
      },
      "AccountSummary": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string",
            "description": "Your account identifier."
          },
          "first_seen": {
            "type": "string",
            "description": "When InferTrail first saw the account."
          },
          "last_seen": {
            "type": "string",
            "description": "When InferTrail last saw activity."
          },
          "subscription_tier": {
            "type": [
              "string",
              "null"
            ],
            "description": "The subscription tier you reported."
          },
          "request_count": {
            "type": "integer",
            "description": "Scored requests for the account."
          },
          "last_label": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "fraud",
              "legitimate",
              null
            ],
            "description": "Your most recent label."
          },
          "last_label_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When you labelled the account."
          },
          "latest_score": {
            "type": [
              "number",
              "null"
            ],
            "description": "The most recent score."
          },
          "latest_tier": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "low",
              "medium",
              "high",
              null
            ],
            "description": "The most recent tier."
          },
          "scored_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the most recent score was given."
          },
          "inference_cost_usd": {
            "type": "number",
            "description": "Spend in the window, in US dollars."
          }
        },
        "required": [
          "account_id",
          "first_seen",
          "last_seen",
          "subscription_tier",
          "request_count",
          "last_label",
          "last_label_at",
          "latest_score",
          "latest_tier",
          "scored_at",
          "inference_cost_usd"
        ]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request is malformed, too large, or contains prompt or response content.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Invalid metadata request."
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The API key is missing, unknown, revoked, or not a secret key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "API key required or invalid."
            }
          }
        }
      },
      "Forbidden": {
        "description": "The key may not use this route.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Nothing with that identifier belongs to your workspace.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "Wrong HTTP method; the `Allow` header names the right one.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "Another request with the same idempotency key is still in progress.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooLarge": {
        "description": "The batch exceeds its size limit.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "The key exceeded its request rate. Retry after a short wait.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unavailable": {
        "description": "InferTrail could not complete the request. Retry with the same `event_id`; it will not be recorded twice.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Timeout": {
        "description": "The request did not finish in time. Retry with the same idempotency key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
