# Usama Kelani API Documentation

> Authentication, endpoints, schemas, error codes, cache behavior, and working examples for the public portfolio API.

## Base URL and authentication

The production base URL is https://usamakelani.com. All public reads are unauthenticated and return application/json. GET and HEAD are supported on read-only resources; HEAD returns the same status and headers without a body. Requests to www redirect to the canonical host and keep the path and query.

Only the site operator may POST a sanitized observation to /api/homelab using Authorization: Bearer <operator credential>. This endpoint retains the existing 32 KiB limit and privacy allowlist. Public integrations should use GET only; no private control endpoints or client-product APIs are exposed.


## Endpoints and schemas

GET /api lists the API version and public resource links. GET /api/v1/profile returns the published profile, contact details, skills, work history, and listed credentials. GET /api/v1/projects returns selected projects. GET /api/v1/case-studies lists the published studies; GET /api/v1/case-studies/{slug} returns one full study. Valid slugs are ordex, ondemand, and learning-hub.

GET /api/v1/sandbox/profile is a fixed, read-only integration fixture. GET /api/homelab returns the latest sanitized public observation, which can be stale; inspect generatedAt and treat observations older than 90 seconds as a last snapshot. An empty feed returns 503. /openapi.json defines the typed response schemas and unique operation IDs for function-calling tools.

```sh
curl -sS https://usamakelani.com/api
curl -sS https://usamakelani.com/api/v1/projects
curl -sS https://usamakelani.com/api/v1/case-studies/ordex
```

- [OpenAPI specification](https://usamakelani.com/openapi.json)

## Structured errors

Errors use {"error":{"code":"NOT_FOUND","message":"…","hint":"…","docs":"https://usamakelani.com/docs"}}. Use the HTTP status and stable code for control flow. Unknown API paths or case studies return 404; unsupported methods return 405 with Allow; operator writes may return 400, 401, 409, or 413. Backend failures return 503 or 500 with a retry hint and no internal details.

Unauthenticated writes return 401 and a WWW-Authenticate bearer challenge. The public API does not accept writes. Do not retry 400, 401, 404, 405, 409, or 413 without resolving the hint; back off after 500 or 503. A 503 feed response includes Retry-After: 15.

```sh
curl -sS -i https://usamakelani.com/api/v1/does-not-exist
```


## Caching, limits, and Markdown

Published profile and project responses can be cached for one hour. Live observations and errors use Cache-Control: no-store. There is no application-level read quota; hosting protection can still limit traffic. Keep requests bounded, cache static content, and use modest polling only when a live observation is needed.

Requests to supported pages with Accept: text/markdown receive Markdown and Vary: Accept. Accept quality weights are respected; an explicit Markdown preference is needed, so normal browsers and */* requests keep HTML. Markdown variants also have predictable .md URLs. Unknown pages requested as Markdown retain HTTP 404 and link to the docs, llms.txt, and sitemap.

```sh
curl -sS -L -i -H 'Accept: text/markdown' https://usamakelani.com/
curl -sS -L -i -H 'Accept: text/html' https://usamakelani.com/
curl -sS -L -i -H 'Accept: text/markdown' https://usamakelani.com/does-not-exist
```