VetFlash API

Authentication

Send a bearer token in the Authorization header. There are two kinds:

{
  "error": {
    "message": "Invalid or missing credentials.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

OAuth 2.0 (authorization code + PKCE)

Register an app in OAuth apps to get a client ID (and a secret for confidential apps). PKCE with S256 is required for every client. Server metadata lives at https://vetflash.io/.well-known/oauth-authorization-server.

1. 1. Send the vet to the consent screen

   Generate a random code_verifier (43-128 characters) and a state. The vet signs in, reviews the scopes and approves. We redirect back to your exact registered redirect_uri with code and state.

   https://vetflash.io/oauth/authorize
     ?response_type=code
     &client_id=vfc_...
     &redirect_uri=https://yourapp.com/callback
     &scope=profile:read chat:write
     &state=RANDOM_STATE
     &code_challenge=BASE64URL(SHA256(code_verifier))
     &code_challenge_method=S256

2. 2. Exchange the code

   Codes expire after 10 minutes and work once. Confidential clients authenticate with HTTP Basic (or client_secret in the body); public clients send client_id only.

   Exchange

   curl -X POST https://vetflash.io/api/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=authorization_code \
     -d code=vfac_... \
     -d redirect_uri=https://yourapp.com/callback \
     -d code_verifier=$CODE_VERIFIER

   {
     "access_token": "vfat_...",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "vfrt_...",
     "scope": "profile:read chat:write"
   }

3. 3. Refresh and revoke

   Access tokens last one hour. Refresh tokens last 30 days and rotate on every use; presenting an already-used refresh token revokes the whole connection.

   RefreshRevoke

   curl -X POST https://vetflash.io/api/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=refresh_token \
     -d refresh_token=vfrt_...

Scopes

API keys get all 6 scopes unless you narrow them. A call without the required scope returns 403 with code: "insufficient_scope".

Credits & billing

Calls spend the credits on the account behind the key or token, at exactly the in-app rate. Every response reports what it cost (X-VetFlash-Credits-Charged header or a vetflash / credits_charged field). Failed generations are refunded automatically, and max_credits rejects a chat request that would cost more than you allow.

Legacy model names still work: vetflash-ask → vetflash, vetflash-vetflow → vetflow.

Errors

Errors share one shape. Every response carries an X-Request-Id; include it when you contact us.

Rate limits

60 requests per 60 seconds per API key or OAuth connection. Over the limit you get 429 with a Retry-After header. Ask session links are separately limited to 20 visitor messages a minute.

Streaming

Set "stream": true on chat completions to receive server-sent events in the OpenAI format. VetFlash M2 streams its reasoning as delta.reasoning_content while it researches, then the clinically reviewed answer as delta.content. The final chunk includes the credits charged.

data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":""}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"reasoning_content":"Considering GI vs systemic causes..."}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Top differentials: "}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop"}],"vetflash":{"credits_charged":10}}

data: [DONE]