Skip to content

API Documentation

Jump to bottom
Amit edited this page May 29, 2026 · 1 revision

API Documentation

The IBF-SLM application exposes a REST API built with FastAPI. The base URL for local development is http://localhost:8000.

Interactive API explorers are available at:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

Both are generated automatically from the OpenAPI schema and reflect the live server's current routes and models.

Authentication

IBF-SLM uses JWT-based authentication. The token is issued on login and must accompany every subsequent request.

Client type How the token is stored How to pass it
Browser httponly cookie (set automatically by Set-Cookie) Cookie is sent automatically by the browser
API / CLI Caller stores the token Authorization: Bearer <token> header

Register

Create a new user account.

POST /register

Request body (JSON)

{
  "username": "alice",
  "email": "alice@example.com",
  "password": "s3cr3t!"
}

Response 201 Created

{
  "id": 1,
  "username": "alice",
  "email": "alice@example.com"
}

curl

curl -s -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","email":"alice@example.com","password":"s3cr3t!"}'

Login

Authenticate and obtain a JWT.

POST /login

Request body (JSON)

{
  "username": "alice",
  "password": "s3cr3t!"
}

Response 200 OK

Browser clients receive the token in a Set-Cookie: access_token=<jwt>; HttpOnly header. API clients receive it in the response body as well:

{
  "access_token": "<jwt>",
  "token_type": "bearer"
}

curl — capture the token for subsequent API calls

TOKEN=$(curl -s -X POST http://localhost:8000/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"s3cr3t!"}' \
  | jq -r '.access_token')

To use cookie-based auth (mirrors browser behaviour):

curl -s -X POST http://localhost:8000/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"s3cr3t!"}' \
  -c cookies.txt

Logout

Invalidate the current session and clear the cookie.

POST /logout

Requires authentication.

Response 200 OK

{
  "message": "Successfully logged out"
}

curl

# Bearer token
curl -s -X POST http://localhost:8000/logout \
  -H "Authorization: Bearer $TOKEN"

# Cookie
curl -s -X POST http://localhost:8000/logout \
  -b cookies.txt -c cookies.txt

Using the Token on Subsequent Requests

All protected endpoints require a valid JWT. Pass it as a Bearer token:

curl -s http://localhost:8000/dashboard \
  -H "Authorization: Bearer $TOKEN"

Or, if using cookies captured with -c cookies.txt:

curl -s http://localhost:8000/dashboard \
  -b cookies.txt

Dashboard

Base path: /dashboard

Returns summary statistics and overview data for the authenticated user's workspace.

Get Dashboard

GET /dashboard

Requires authentication.

Query parameters — none required; optional filters may be applied (see /docs for full schema).

Response 200 OK

{
  "summary": {
    "total_documents": 42,
    "total_evaluations": 17,
    "last_activity": "2026-05-28T14:32:00Z"
  },
  "recent_activity": []
}

curl

curl -s http://localhost:8000/dashboard \
  -H "Authorization: Bearer $TOKEN"

Data

Base path: /data

Manage raw data records ingested into the system.

List Data Records

GET /data

Requires authentication.

Query parameters

Parameter Type Default Description
skip integer 0 Pagination offset
limit integer 100 Maximum records returned

Response 200 OK

[
  {
    "id": 1,
    "name": "dataset-01",
    "created_at": "2026-05-01T10:00:00Z"
  }
]

curl

curl -s "http://localhost:8000/data?skip=0&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Get Data Record

GET /data/{id}

Requires authentication.

Path parameters

Parameter Type Description
id integer ID of the data record

Response 200 OK

{
  "id": 1,
  "name": "dataset-01",
  "content": "...",
  "created_at": "2026-05-01T10:00:00Z"
}

Response 404 Not Found if the record does not exist.

curl

curl -s http://localhost:8000/data/1 \
  -H "Authorization: Bearer $TOKEN"

Create Data Record

POST /data

Requires authentication.

Request body (JSON)

{
  "name": "dataset-02",
  "content": "raw text or structured payload"
}

Response 201 Created

{
  "id": 2,
  "name": "dataset-02",
  "created_at": "2026-05-29T08:00:00Z"
}

curl

curl -s -X POST http://localhost:8000/data \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"dataset-02","content":"raw text or structured payload"}'

Delete Data Record

DELETE /data/{id}

Requires authentication.

Response 204 No Content on success.

curl

curl -s -X DELETE http://localhost:8000/data/2 \
  -H "Authorization: Bearer $TOKEN"

Corpus

Base path: /corpus

Manage document corpora used for language model fine-tuning and evaluation.

List Corpora

GET /corpus

Requires authentication.

Query parameters

Parameter Type Default Description
skip integer 0 Pagination offset
limit integer 100 Maximum records returned

Response 200 OK

[
  {
    "id": 1,
    "name": "legal-corpus-v1",
    "document_count": 250,
    "created_at": "2026-04-10T09:00:00Z"
  }
]

curl

curl -s "http://localhost:8000/corpus?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Get Corpus

GET /corpus/{id}

Requires authentication.

Response 200 OK

{
  "id": 1,
  "name": "legal-corpus-v1",
  "document_count": 250,
  "documents": [],
  "created_at": "2026-04-10T09:00:00Z"
}

curl

curl -s http://localhost:8000/corpus/1 \
  -H "Authorization: Bearer $TOKEN"

Create Corpus

POST /corpus

Requires authentication.

Request body (JSON)

{
  "name": "legal-corpus-v2",
  "data_ids": [1, 2, 3]
}

data_ids is the list of data record IDs (from /data) to include in the corpus.

Response 201 Created

{
  "id": 2,
  "name": "legal-corpus-v2",
  "document_count": 3,
  "created_at": "2026-05-29T08:15:00Z"
}

curl

curl -s -X POST http://localhost:8000/corpus \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"legal-corpus-v2","data_ids":[1,2,3]}'

Delete Corpus

DELETE /corpus/{id}

Requires authentication.

Response 204 No Content on success.

curl

curl -s -X DELETE http://localhost:8000/corpus/2 \
  -H "Authorization: Bearer $TOKEN"

Eval

Base path: /eval

Run and retrieve evaluation jobs that benchmark a small language model against a corpus.

List Evaluations

GET /eval

Requires authentication.

Query parameters

Parameter Type Default Description
skip integer 0 Pagination offset
limit integer 100 Maximum records returned
corpus_id integer — Filter by corpus

Response 200 OK

[
  {
    "id": 1,
    "corpus_id": 1,
    "status": "completed",
    "score": 0.87,
    "created_at": "2026-05-20T12:00:00Z"
  }
]

curl

curl -s "http://localhost:8000/eval?corpus_id=1" \
  -H "Authorization: Bearer $TOKEN"

Get Evaluation

GET /eval/{id}

Requires authentication.

Response 200 OK

{
  "id": 1,
  "corpus_id": 1,
  "status": "completed",
  "score": 0.87,
  "metrics": {
    "precision": 0.90,
    "recall": 0.84,
    "f1": 0.87
  },
  "created_at": "2026-05-20T12:00:00Z",
  "completed_at": "2026-05-20T12:04:38Z"
}

curl

curl -s http://localhost:8000/eval/1 \
  -H "Authorization: Bearer $TOKEN"

Create Evaluation

Enqueue a new evaluation job.

POST /eval

Requires authentication.

Request body (JSON)

{
  "corpus_id": 1,
  "model_config": {
    "model_name": "slm-v2",
    "max_tokens": 512
  }
}
Field Type Required Description
corpus_id integer yes Corpus to evaluate against
model_config object yes Model identifier and inference parameters

Response 202 Accepted

The job is queued asynchronously. Poll GET /eval/{id} to check status.

{
  "id": 5,
  "corpus_id": 1,
  "status": "pending",
  "created_at": "2026-05-29T08:30:00Z"
}

status values: pending → running → completed | failed

curl

curl -s -X POST http://localhost:8000/eval \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"corpus_id":1,"model_config":{"model_name":"slm-v2","max_tokens":512}}'

Delete Evaluation

DELETE /eval/{id}

Requires authentication. Only evaluations with status pending or failed can be deleted.

Response 204 No Content on success.

Response 409 Conflict if the evaluation is currently running.

curl

curl -s -X DELETE http://localhost:8000/eval/5 \
  -H "Authorization: Bearer $TOKEN"

Error Responses

All errors follow a consistent envelope:

{
  "detail": "Human-readable error message"
}
HTTP status Meaning
400 Bad Request Malformed request or validation failure
401 Unauthorized Missing or invalid JWT
403 Forbidden Authenticated but not authorised for this resource
404 Not Found Resource does not exist
409 Conflict State conflict (e.g. deleting a running job)
422 Unprocessable Entity Request body fails schema validation (FastAPI default)
500 Internal Server Error Unexpected server-side error

OpenAPI Schema

The machine-readable OpenAPI 3.x schema is served at:

GET http://localhost:8000/openapi.json

You can import this URL directly into Postman, Insomnia, or any OpenAPI-compatible tooling.

Clone this wiki locally