↳ DOCUMENTATION

API Reference

Base URL: https://api.project-block.com

Install

pip install projectblock

Using LangChain? pip install projectblock[langchain] adds a drop-in callback handler — see below.

Authentication

Every request needs your API key as a Bearer token. Find yours on the dashboard after signing up.

Authorization: Bearer pb_your_api_key_here

Quickstart (Python SDK)

import os
os.environ["PROJECTBLOCK_API_KEY"] = "pb_your_key"

from projectblock import gate, record

await gate("user_123", budget_usd=5.00)
response = await openai.chat.completions.create(model="gpt-4o", messages=messages)
await record("user_123", model="gpt-4o", cost_usd=0.0023)

Endpoints

POST/v1/gate

Check whether a user still has budget left before you call your LLM. Returns 401 with an Invalid API key message if the key is wrong.

curl -X POST https://api.project-block.com/v1/gate \
  -H "Authorization: Bearer pb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"usr_123","budget_usd":5.00}'

→ {"allowed":true,"remaining_usd":5.0,"used_usd":0.0}

POST/v1/record

Meter and audit a completed AI call in one call. Always async on our side — never adds latency to your user-facing request.

curl -X POST https://api.project-block.com/v1/record \
  -H "Authorization: Bearer pb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"usr_123","model":"gpt-4o","cost_usd":0.0023}'

→ {"ok":true,"event_id":"...","monthly_cost_usd":0.0023,"remaining_usd":4.9977}

GET/v1/usage/{user_id}

Current month usage for a single end-user.

curl https://api.project-block.com/v1/usage/usr_123 \
  -H "Authorization: Bearer pb_your_key"

→ {"cost_usd":0.0023,"tokens":350,"events":1,"budget_usd":5.0,"used_pct":0.05}

GET/v1/audit/stream

Most recent audit events for your organization, newest first.

curl https://api.project-block.com/v1/audit/stream \
  -H "Authorization: Bearer pb_your_key"

POST/v1/webhooks

Register a webhook endpoint. Budget alerts (80/95/100%) are delivered here, signed with HMAC-SHA256 in the X-ProjectBlock-Signature header.

curl -X POST https://api.project-block.com/v1/webhooks \
  -H "Authorization: Bearer pb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yourapp.com/webhook","events":["budget.80","budget.95","budget.100"]}'

GET/v1/compliance/report?period=YYYY-MM

Download a PDF EU AI Act compliance report (Article 12 record-keeping) for a given month.

curl "https://api.project-block.com/v1/compliance/report?period=2026-06" \
  -H "Authorization: Bearer pb_your_key" \
  -o report.pdf

DELETE/v1/gdpr/user/{user_id}

Right-to-be-forgotten for one end-user. Pseudonymizes their identifier across all audit events; preserves timestamp, model, and cost fields required for AI Act retention.

curl -X DELETE https://api.project-block.com/v1/gdpr/user/usr_123 \
  -H "Authorization: Bearer pb_your_key"

→ {"ok":true,"pseudonym":"deleted_a0053e6d...","events_anonymized":4}

LangChain integration

Drop ProjectBlockCallbackHandler into any LangChain callbacks=[...] list to get automatic budget gating, usage metering, and audit logging for every LLM call — no other changes to your chain.

from langchain_openai import ChatOpenAI
from projectblock.langchain import ProjectBlockCallbackHandler

handler = ProjectBlockCallbackHandler(
    user_id="usr_123",
    budget_usd=5.00,
    cost_per_1k_input=0.0025,   # set to your model's real pricing
    cost_per_1k_output=0.01,
)

llm = ChatOpenAI(model="gpt-4o", callbacks=[handler])
response = await llm.ainvoke("Hello!")
# Budget checked before the call. Usage + audit event recorded after.

Need more?

The full interactive Swagger reference, with every parameter and response schema, is at api.project-block.com/docs.