Build a Praxa backend with FastAPI

​

Prerequisites

• a trusted server runtime and application authentication boundary;
• a disposable personal workspace Praxa key with only the tutorial’s required scopes;
• synthetic input plus a persisted application request ID for replay tests;
• a fake upstream for unit tests and a non-production environment for canaries;
• an acceptance assertion that proves the FastAPI dependency boundary admits one task and maps failures without leaking upstream data.

​

1. Install dependencies

python -m pip install fastapi uvicorn httpx pytest
export PRAXA_API_KEY="praxa_sk_<redacted>"

​

2. Implement the route

import hashlib
import os
import httpx
from fastapi import Depends, FastAPI, HTTPException, Response
from pydantic import BaseModel, Field

app = FastAPI()

class TaskInput(BaseModel):
    task: str = Field(min_length=1, max_length=16_000)
    request_id: str = Field(alias="requestId", min_length=16, max_length=128)

@app.post("/api/tasks")
async def create_task(
    body: TaskInput,
    response: Response,
    user=Depends(require_user),
):
    digest = hashlib.sha256(
        f"{user.id}\0{body.request_id}".encode()
    ).hexdigest()
    key = f"fastapi:{digest}"

    async with httpx.AsyncClient(timeout=30) as client:
        upstream = await client.post(
            "https://api.praxa.io/v1/execute",
            headers={
                "Authorization": f"Bearer {os.environ['PRAXA_API_KEY']}",
                "Idempotency-Key": key,
            },
            json={
                "apiVersion": "v1",
                "requestId": key,
                "mode": "task",
                "task": {"input": body.task},
                "idempotencyKey": key,
            },
        )

    if upstream.status_code >= 400:
        raise HTTPException(
            upstream.status_code,
            "Praxa request failed",
            headers={"Cache-Control": "no-store"},
        )
    response.headers["Cache-Control"] = "no-store"
    return upstream.json()

​

3. Test with dependency overrides

from fastapi.testclient import TestClient
from app.main import app, require_user

class User:
    id = "test-user"

app.dependency_overrides[require_user] = lambda: User()
client = TestClient(app)

def test_rejects_invalid_task():
    response = client.post(
        "/api/tasks",
        json={"task": "", "requestId": "request-00000001"},
    )
    assert response.status_code == 422

​

4. Run the live acceptance check

uvicorn app.main:app --reload
pytest -q

​

Troubleshooting

​

Best practices

• Create one AsyncClient at application startup and close it at shutdown.
• Resolve the user with a dependency before calling Praxa.
• Bound Pydantic models and request-body size.
• Do not include tenant, owner, scope, or Praxa key in the request model.
• Keep error details redacted and responses no-store.
• Use HTTPX MockTransport for unit tests and disposable keys for canaries.

​

Optimize for production

• Reuse one configured HTTP or SDK client per process and bound concurrent upstream work.
• Prefer durable admission plus asynchronous readback over holding application requests open.
• Cache only non-sensitive, tenant-scoped reads within their documented freshness window.
• Measure p50/p95 latency, admission-to-terminal time, retries, conflicts, and connection reuse before tuning.

​

Cleanup and next steps

1. Revoke the disposable Praxa key and require a later request to fail.
2. Remove synthetic application records and any temporary environment files.
3. Cancel or archive unresolved test runs according to the application policy.
4. Retain only redacted request, run, and verification identifiers needed for the test record.

​

Frequently asked questions

​

What proves this tutorial works?

​

Can a browser, mobile app, or model prompt hold the credential?

​

How should an ambiguous mutation be retried?

​

What should we monitor after release?