# API reference

Base URL: `https://www.muslimjobs.io/api/partner/v1`

The feed is read only. Every response is JSON except the XML feed and the logos. An [OpenAPI description](/developers/openapi.json) is also available.

## Authentication

Send your key in the `Authorization` header, as a bearer token:

```bash
curl -H "Authorization: Bearer $MUSLIMJOBS_KEY" "https://www.muslimjobs.io/api/partner/v1/jobs"
```

Tools that only speak Basic auth, such as some feed readers, can send the key as the password; the username can be anything, such as `feed`. A key sent as the username is refused with `400 key_in_username`:

```bash
curl -u "feed:$MUSLIMJOBS_KEY" "https://www.muslimjobs.io/api/partner/v1/jobs.xml"
```

or, where a tool asks for one URL: `https://feed:YOUR_KEY@www.muslimjobs.io/api/partner/v1/jobs.xml`.

**Never put your key in the query string.** URLs end up in logs and browser history. A request with `?key=` is refused with `400 key_in_url`; treat that key as exposed, create a new one and revoke it.

## List jobs

`GET /jobs`

| Parameter | Description |
| --- | --- |
| `limit` | Jobs per page, 1 to 100. Default 100. |
| `cursor` | The `next_cursor` from the previous page. Leave it out for the first page. |

Returns `{ "data": [job, …], "next_cursor": "…" | null }`. Jobs are ordered by id. See [the job object](/developers/docs/job-object).

## Get one job

`GET /jobs/{id}`

Returns one job object. A job that has closed returns `410 job_ended`; an unknown id returns `404 not_found`.

## XML feed

`GET /jobs.xml`

Every live job in one Indeed-style XML document, for job boards and aggregators that import XML. It’s rebuilt at most every 10 minutes. The fields match the JSON job object; the [job object](/developers/docs/job-object) page shows each XML element.

## Company logos

`GET /logos/{companyId}.png`

The URLs in `company.logo_url`. Public, no key needed, cached for a day. Fetch each once and keep your own copy.

## Responses and errors

Feed responses send:

- `Cache-Control: no-store`, so proxies don’t keep your feed.
- `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds) for the limit that applies.

Errors have one shape:

```json
{ "error": { "code": "invalid_key", "message": "Invalid API key." } }
```

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `key_in_url` | The key was in the URL. Send it in the header, and replace the key. |
| 400 | `key_in_username` | The key was sent as the Basic auth username. Send it as the password, and replace the key. |
| 400 | `invalid_cursor` | The cursor isn’t valid. Start again without one. |
| 400 | `validation_failed` | A parameter is out of range, such as `limit=500`. |
| 401 | `invalid_key` | No key, a wrong key or a revoked key. |
| 403 | `partner_paused` | Your access is paused or has ended. |
| 404 | `not_found` | No job with that id. |
| 410 | `job_ended` | The job has closed. Remove it. |
| 429 | `rate_limited` | Too many requests. Wait for `Retry-After` seconds. |

