{
 "openapi": "3.1.0",
 "info": {
  "title": "Vitals Bio API",
  "version": "2026-11-21",
  "description": "Animal identity, pose, behaviour, health score and forecast from video. Each response states whether its capability is Live, Preview, Pending or off."
 },
 "servers": [
  {
   "url": "https://vitalsbio-console.pages.dev/api"
  }
 ],
 "paths": {
  "/v1/analyze": {
   "post": {
    "operationId": "analyze",
    "summary": "Everything in one result: detection, tracks, identity, pose, behaviour, states.",
    "security": [
     {
      "bearer": []
     }
    ],
    "parameters": [
     {
      "name": "sample",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "cow-lying",
        "dog-walk",
        "brangus-herd",
        "paddock",
        "white-horses"
       ]
      },
      "description": "Answer from a stored result of a real run. No video needed, nothing metered, the response says sample: true."
     },
     {
      "name": "species",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "max_seconds",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.2,
       "maximum": 120
      }
     },
     {
      "name": "start_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     },
     {
      "name": "step_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.02,
       "maximum": 5
      }
     },
     {
      "name": "stream_id",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^[A-Za-z0-9_.:-]{1,64}$"
      },
      "description": "Marks this clip as one segment of a longer stream."
     },
     {
      "name": "segment_index",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     },
     {
      "name": "offset_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "video/mp4": {
       "schema": {
        "type": "string",
        "format": "binary"
       }
      },
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "video_b64"
        ],
        "properties": {
         "video_b64": {
          "type": "string"
         },
         "species": {
          "type": "string"
         },
         "max_seconds": {
          "type": "number"
         },
         "start_s": {
          "type": "number"
         },
         "step_s": {
          "type": "number"
         },
         "stream_id": {
          "type": "string"
         },
         "segment_index": {
          "type": "integer"
         },
         "offset_s": {
          "type": "number"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Quote this when you ask for help."
       },
       "Vitals-Version": {
        "schema": {
         "type": "string"
        },
        "description": "The dated API version that answered."
       },
       "X-RateLimit-Limit": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Remaining": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Reset": {
        "schema": {
         "type": "integer"
        },
        "description": "Unix seconds when the window resets."
       },
       "X-Vitals-Video-Seconds": {
        "schema": {
         "type": "number"
        },
        "description": "Seconds of video metered for this call."
       },
       "X-Quota-Remaining-Minutes": {
        "schema": {
         "type": "number"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Bad request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing, wrong, revoked or expired key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Key scope does not cover this endpoint",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "Video over 25 MB",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "415": {
      "description": "Wrong content type",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "The model could not use this video",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit, monthly quota or key cap",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "The model failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No inference backend; nothing metered",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "504": {
      "description": "Inference timed out",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/identity": {
   "post": {
    "operationId": "identity",
    "summary": "Who is who: one row per tracked animal, with an identity id when one is known.",
    "security": [
     {
      "bearer": []
     }
    ],
    "parameters": [
     {
      "name": "sample",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "cow-lying",
        "dog-walk",
        "brangus-herd",
        "paddock",
        "white-horses"
       ]
      },
      "description": "Answer from a stored result of a real run. No video needed, nothing metered, the response says sample: true."
     },
     {
      "name": "species",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "max_seconds",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.2,
       "maximum": 120
      }
     },
     {
      "name": "start_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     },
     {
      "name": "step_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.02,
       "maximum": 5
      }
     },
     {
      "name": "stream_id",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^[A-Za-z0-9_.:-]{1,64}$"
      },
      "description": "Marks this clip as one segment of a longer stream."
     },
     {
      "name": "segment_index",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     },
     {
      "name": "offset_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     },
     {
      "name": "include_embeddings",
      "in": "query",
      "schema": {
       "type": "boolean"
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "video/mp4": {
       "schema": {
        "type": "string",
        "format": "binary"
       }
      },
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "video_b64"
        ],
        "properties": {
         "video_b64": {
          "type": "string"
         },
         "species": {
          "type": "string"
         },
         "max_seconds": {
          "type": "number"
         },
         "start_s": {
          "type": "number"
         },
         "step_s": {
          "type": "number"
         },
         "stream_id": {
          "type": "string"
         },
         "segment_index": {
          "type": "integer"
         },
         "offset_s": {
          "type": "number"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Quote this when you ask for help."
       },
       "Vitals-Version": {
        "schema": {
         "type": "string"
        },
        "description": "The dated API version that answered."
       },
       "X-RateLimit-Limit": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Remaining": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Reset": {
        "schema": {
         "type": "integer"
        },
        "description": "Unix seconds when the window resets."
       },
       "X-Vitals-Video-Seconds": {
        "schema": {
         "type": "number"
        },
        "description": "Seconds of video metered for this call."
       },
       "X-Quota-Remaining-Minutes": {
        "schema": {
         "type": "number"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PartResponse"
        }
       }
      }
     },
     "400": {
      "description": "Bad request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing, wrong, revoked or expired key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Key scope does not cover this endpoint",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "Video over 25 MB",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "415": {
      "description": "Wrong content type",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "The model could not use this video",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit, monthly quota or key cap",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "The model failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No inference backend; nothing metered",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "504": {
      "description": "Inference timed out",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/pose": {
   "post": {
    "operationId": "pose",
    "summary": "17 keypoints per animal per sampled frame (AP-10K order).",
    "security": [
     {
      "bearer": []
     }
    ],
    "parameters": [
     {
      "name": "sample",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "cow-lying",
        "dog-walk",
        "brangus-herd",
        "paddock",
        "white-horses"
       ]
      },
      "description": "Answer from a stored result of a real run. No video needed, nothing metered, the response says sample: true."
     },
     {
      "name": "species",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "max_seconds",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.2,
       "maximum": 120
      }
     },
     {
      "name": "start_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     },
     {
      "name": "step_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.02,
       "maximum": 5
      }
     },
     {
      "name": "stream_id",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^[A-Za-z0-9_.:-]{1,64}$"
      },
      "description": "Marks this clip as one segment of a longer stream."
     },
     {
      "name": "segment_index",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     },
     {
      "name": "offset_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "video/mp4": {
       "schema": {
        "type": "string",
        "format": "binary"
       }
      },
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "video_b64"
        ],
        "properties": {
         "video_b64": {
          "type": "string"
         },
         "species": {
          "type": "string"
         },
         "max_seconds": {
          "type": "number"
         },
         "start_s": {
          "type": "number"
         },
         "step_s": {
          "type": "number"
         },
         "stream_id": {
          "type": "string"
         },
         "segment_index": {
          "type": "integer"
         },
         "offset_s": {
          "type": "number"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Quote this when you ask for help."
       },
       "Vitals-Version": {
        "schema": {
         "type": "string"
        },
        "description": "The dated API version that answered."
       },
       "X-RateLimit-Limit": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Remaining": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Reset": {
        "schema": {
         "type": "integer"
        },
        "description": "Unix seconds when the window resets."
       },
       "X-Vitals-Video-Seconds": {
        "schema": {
         "type": "number"
        },
        "description": "Seconds of video metered for this call."
       },
       "X-Quota-Remaining-Minutes": {
        "schema": {
         "type": "number"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PartResponse"
        }
       }
      }
     },
     "400": {
      "description": "Bad request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing, wrong, revoked or expired key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Key scope does not cover this endpoint",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "Video over 25 MB",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "415": {
      "description": "Wrong content type",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "The model could not use this video",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit, monthly quota or key cap",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "The model failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No inference backend; nothing metered",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "504": {
      "description": "Inference timed out",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/behavior": {
   "post": {
    "operationId": "behavior",
    "summary": "Behaviour probabilities per animal per sampled frame, with the share of time in each.",
    "security": [
     {
      "bearer": []
     }
    ],
    "parameters": [
     {
      "name": "sample",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "cow-lying",
        "dog-walk",
        "brangus-herd",
        "paddock",
        "white-horses"
       ]
      },
      "description": "Answer from a stored result of a real run. No video needed, nothing metered, the response says sample: true."
     },
     {
      "name": "species",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "max_seconds",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.2,
       "maximum": 120
      }
     },
     {
      "name": "start_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     },
     {
      "name": "step_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.02,
       "maximum": 5
      }
     },
     {
      "name": "stream_id",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^[A-Za-z0-9_.:-]{1,64}$"
      },
      "description": "Marks this clip as one segment of a longer stream."
     },
     {
      "name": "segment_index",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     },
     {
      "name": "offset_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "video/mp4": {
       "schema": {
        "type": "string",
        "format": "binary"
       }
      },
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "video_b64"
        ],
        "properties": {
         "video_b64": {
          "type": "string"
         },
         "species": {
          "type": "string"
         },
         "max_seconds": {
          "type": "number"
         },
         "start_s": {
          "type": "number"
         },
         "step_s": {
          "type": "number"
         },
         "stream_id": {
          "type": "string"
         },
         "segment_index": {
          "type": "integer"
         },
         "offset_s": {
          "type": "number"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Quote this when you ask for help."
       },
       "Vitals-Version": {
        "schema": {
         "type": "string"
        },
        "description": "The dated API version that answered."
       },
       "X-RateLimit-Limit": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Remaining": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Reset": {
        "schema": {
         "type": "integer"
        },
        "description": "Unix seconds when the window resets."
       },
       "X-Vitals-Video-Seconds": {
        "schema": {
         "type": "number"
        },
        "description": "Seconds of video metered for this call."
       },
       "X-Quota-Remaining-Minutes": {
        "schema": {
         "type": "number"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PartResponse"
        }
       }
      }
     },
     "400": {
      "description": "Bad request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing, wrong, revoked or expired key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Key scope does not cover this endpoint",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "Video over 25 MB",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "415": {
      "description": "Wrong content type",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "The model could not use this video",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit, monthly quota or key cap",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "The model failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No inference backend; nothing metered",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "504": {
      "description": "Inference timed out",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/health-score": {
   "post": {
    "operationId": "health_score",
    "summary": "A 0 to 100 roll-up per animal. Null unless a validated state reading exists. Labelled ESTIMATE. Not veterinary advice.",
    "security": [
     {
      "bearer": []
     }
    ],
    "parameters": [
     {
      "name": "sample",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "cow-lying",
        "dog-walk",
        "brangus-herd",
        "paddock",
        "white-horses"
       ]
      },
      "description": "Answer from a stored result of a real run. No video needed, nothing metered, the response says sample: true."
     },
     {
      "name": "species",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "max_seconds",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.2,
       "maximum": 120
      }
     },
     {
      "name": "start_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     },
     {
      "name": "step_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.02,
       "maximum": 5
      }
     },
     {
      "name": "stream_id",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^[A-Za-z0-9_.:-]{1,64}$"
      },
      "description": "Marks this clip as one segment of a longer stream."
     },
     {
      "name": "segment_index",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     },
     {
      "name": "offset_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "video/mp4": {
       "schema": {
        "type": "string",
        "format": "binary"
       }
      },
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "video_b64"
        ],
        "properties": {
         "video_b64": {
          "type": "string"
         },
         "species": {
          "type": "string"
         },
         "max_seconds": {
          "type": "number"
         },
         "start_s": {
          "type": "number"
         },
         "step_s": {
          "type": "number"
         },
         "stream_id": {
          "type": "string"
         },
         "segment_index": {
          "type": "integer"
         },
         "offset_s": {
          "type": "number"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Quote this when you ask for help."
       },
       "Vitals-Version": {
        "schema": {
         "type": "string"
        },
        "description": "The dated API version that answered."
       },
       "X-RateLimit-Limit": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Remaining": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Reset": {
        "schema": {
         "type": "integer"
        },
        "description": "Unix seconds when the window resets."
       },
       "X-Vitals-Video-Seconds": {
        "schema": {
         "type": "number"
        },
        "description": "Seconds of video metered for this call."
       },
       "X-Quota-Remaining-Minutes": {
        "schema": {
         "type": "number"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PartResponse"
        }
       }
      }
     },
     "400": {
      "description": "Bad request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing, wrong, revoked or expired key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Key scope does not cover this endpoint",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "Video over 25 MB",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "415": {
      "description": "Wrong content type",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "The model could not use this video",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit, monthly quota or key cap",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "The model failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No inference backend; nothing metered",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "504": {
      "description": "Inference timed out",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/forecast": {
   "post": {
    "operationId": "forecast",
    "summary": "Where each animal is expected to be next. Check capability.status: it is Pending until its locked test is scored.",
    "security": [
     {
      "bearer": []
     }
    ],
    "parameters": [
     {
      "name": "sample",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "cow-lying",
        "dog-walk",
        "brangus-herd",
        "paddock",
        "white-horses"
       ]
      },
      "description": "Answer from a stored result of a real run. No video needed, nothing metered, the response says sample: true."
     },
     {
      "name": "species",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "max_seconds",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.2,
       "maximum": 120
      }
     },
     {
      "name": "start_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     },
     {
      "name": "step_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0.02,
       "maximum": 5
      }
     },
     {
      "name": "stream_id",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^[A-Za-z0-9_.:-]{1,64}$"
      },
      "description": "Marks this clip as one segment of a longer stream."
     },
     {
      "name": "segment_index",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     },
     {
      "name": "offset_s",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "video/mp4": {
       "schema": {
        "type": "string",
        "format": "binary"
       }
      },
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "video_b64"
        ],
        "properties": {
         "video_b64": {
          "type": "string"
         },
         "species": {
          "type": "string"
         },
         "max_seconds": {
          "type": "number"
         },
         "start_s": {
          "type": "number"
         },
         "step_s": {
          "type": "number"
         },
         "stream_id": {
          "type": "string"
         },
         "segment_index": {
          "type": "integer"
         },
         "offset_s": {
          "type": "number"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Quote this when you ask for help."
       },
       "Vitals-Version": {
        "schema": {
         "type": "string"
        },
        "description": "The dated API version that answered."
       },
       "X-RateLimit-Limit": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Remaining": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Reset": {
        "schema": {
         "type": "integer"
        },
        "description": "Unix seconds when the window resets."
       },
       "X-Vitals-Video-Seconds": {
        "schema": {
         "type": "number"
        },
        "description": "Seconds of video metered for this call."
       },
       "X-Quota-Remaining-Minutes": {
        "schema": {
         "type": "number"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PartResponse"
        }
       }
      }
     },
     "400": {
      "description": "Bad request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing, wrong, revoked or expired key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Key scope does not cover this endpoint",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "Video over 25 MB",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "415": {
      "description": "Wrong content type",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "The model could not use this video",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit, monthly quota or key cap",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "The model failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No inference backend; nothing metered",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "504": {
      "description": "Inference timed out",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/health": {
   "get": {
    "operationId": "health",
    "summary": "Is an inference backend reachable?",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/v1/schema": {
   "get": {
    "operationId": "schema",
    "summary": "The JSON Schema of the /v1/analyze result.",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/v1/capabilities": {
   "get": {
    "operationId": "capabilities",
    "summary": "What is Live, Preview, Pending or off, from the locked results.",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/v1/samples": {
   "get": {
    "operationId": "samples",
    "summary": "Ids usable with ?sample=.",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/v1/me": {
   "get": {
    "operationId": "me",
    "summary": "The plan, limits and this month's usage for the calling key.",
    "security": [
     {
      "bearer": []
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "An API key from the console: vb_..."
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "required": [
     "error"
    ],
    "properties": {
     "error": {
      "type": "object",
      "required": [
       "type",
       "code",
       "message",
       "request_id",
       "doc_url"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "invalid_request_error",
         "authentication_error",
         "permission_error",
         "not_found_error",
         "rate_limit_error",
         "api_error",
         "inference_error",
         "inference_unavailable"
        ]
       },
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       },
       "param": {
        "type": "string"
       },
       "request_id": {
        "type": "string"
       },
       "doc_url": {
        "type": "string"
       }
      }
     }
    }
   },
   "Result": {
    "type": "object",
    "description": "See /v1/schema (biomodel-v0.1)."
   },
   "PartResponse": {
    "type": "object",
    "required": [
     "object",
     "request_id",
     "api_version",
     "capability",
     "sample",
     "animals",
     "usage"
    ],
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "identity",
       "pose",
       "behavior",
       "health-score",
       "forecast"
      ]
     },
     "request_id": {
      "type": "string"
     },
     "api_version": {
      "type": "string"
     },
     "schema_version": {
      "type": [
       "string",
       "null"
      ]
     },
     "capability": {
      "type": "object",
      "properties": {
       "id": {
        "type": "string"
       },
       "name": {
        "type": "string"
       },
       "status": {
        "type": "string",
        "enum": [
         "live",
         "preview",
         "pending",
         "off",
         "unknown"
        ]
       },
       "mode": {
        "type": [
         "string",
         "null"
        ]
       },
       "label": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     },
     "sample": {
      "type": "boolean"
     },
     "video": {
      "type": [
       "object",
       "null"
      ]
     },
     "model": {
      "type": [
       "object",
       "null"
      ]
     },
     "animals": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "keypoint_names": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "note": {
      "type": "string"
     },
     "stream": {
      "type": "object",
      "properties": {
       "id": {
        "type": "string"
       },
       "segment_index": {
        "type": "integer"
       },
       "offset_s": {
        "type": "number"
       }
      }
     },
     "usage": {
      "type": "object",
      "properties": {
       "video_seconds": {
        "type": "number"
       }
      }
     }
    }
   }
  }
 }
}