Developers
Scalar and OpenAPI
Scalar is the human API reference. OpenAPI 3.1 is the machine-readable contract for tooling, tests, and generated clients.
API reference
Start from the reference, then wire authentication
Treat Scalar as the main place to inspect and try the API. Treat OpenAPI as the source contract for automated consumers and integration tooling.
Reference workflow
The docs are split by how developers consume them.
Live
For humans
Use Scalar to browse endpoints and response examples.
For tooling
Use OpenAPI 3.1 JSON for generated clients and contract checks.
For scripts
Create an API key, then send it as a Bearer token.
Authentication
Send API keys as Bearer tokens
Create API keys from Profile. The full key is shown once. Store it like a password and rotate it when access should change.
New keys use ajg_key_. Legacy ajg_diag_ keys remain valid for compatibility.
Current API
Documented account access
Read only
| API key verification | Available | Use Bearer API keys to verify ownership. |
|---|---|---|
| Key metadata | Available | List non-secret key metadata for the authenticated owner. |
| Jobs | Available | Search and retrieve job listings via API key. GET /api/v1/jobs. Requires Cognito browser session. |
| Profile | Planned | Requires Cognito browser session. |
| Documents | Planned | Requires Cognito browser session. |
| Analysis | Planned | Requires Cognito browser session. |
| Scoped writes | Planned | Write access needs scopes, audit logs, and rate limits before release. |
Endpoints
Routes in the current OpenAPI contract
These routes are documented in Scalar and exported through the OpenAPI 3.1 JSON contract.
| Method | Path | Auth | Status | Use |
|---|---|---|---|---|
| GET | /api/api-keys/whoami | API key | Active | Confirm a key is active and identify the owner. |
| GET | /api/user-api-keys | API key or session | Active | Return non-secret metadata for the owner's keys. |
| POST | /api/user-api-keys | Browser session | Active | Create a key from Profile. The plaintext value is shown once. |
| DELETE | /api/user-api-keys | Browser session | Active | Revoke a key immediately. |
| GET | /api/v1/jobs | API key | Active | Search and retrieve job listings |
| GET | /api/diagnostics/whoami | API key | Compatibility | Deprecated alias for /api/api-keys/whoami. |
Jobs
Search and retrieve job listings
Search and retrieve job listings from the JOBMagical database.
| Parameter | Type | Required | Default | Example |
|---|---|---|---|---|
q | string | No | — | q=software engineer |
location | string | No | — | location=Remote Pakistan |
work_model | string | No | — | work_model=remote |
employment_type | string | No | — | employment_type=full-time |
posted_after | ISO datetime | No | — | posted_after=2026-07-01T00:00:00Z |
sources | comma-separated | No | — | sources=greenhouse,lever |
page | integer | No | 1 | page=1 |
page_size | integer | No | 10 | page_size=25 |
Limits
- Rate limit: 10 requests per minute per API key
- Max page size: 25
- Date format: ISO 8601 (e.g. 2026-07-01T00:00:00Z)
Verify the current key
curl https://jobmagical.com/api/api-keys/whoami \
-H "Authorization: Bearer ajg_key_..."List key metadata
curl https://jobmagical.com/api/user-api-keys \
-H "Authorization: Bearer ajg_key_..."Search jobs
curl "https://jobmagical.com/api/v1/jobs?q=software+engineer&location=pakistan&page_size=10" \
-H "Authorization: Bearer ajg_key_..."Filter by work model
curl "https://jobmagical.com/api/v1/jobs?work_model=remote&employment_type=full-time" \
-H "Authorization: Bearer ajg_key_..."Filter by date
curl "https://jobmagical.com/api/v1/jobs?posted_after=2026-06-15T00:00:00Z&page_size=25" \
-H "Authorization: Bearer ajg_key_..."Filter by source
curl "https://jobmagical.com/api/v1/jobs?sources=greenhouse,lever&page_size=10" \
-H "Authorization: Bearer ajg_key_..."Pagination
curl "https://jobmagical.com/api/v1/jobs?q=software+engineer&page=2&page_size=25" \
-H "Authorization: Bearer ajg_key_..."Combined filters
curl "https://jobmagical.com/api/v1/jobs?q=react+developer&location=remote&work_model=remote&employment_type=full-time&posted_after=2026-06-15T00:00:00Z&sources=greenhouse&page=1&page_size=25" \
-H "Authorization: Bearer ajg_key_..."