QudraQudra Docs
Get API key

Jobs API

The Jobs resource is the heart of the Qudra Partner API. Every job you create flows through the embedding pipeline and becomes matchable against the Qudra seeker graph within ~30 seconds.

The job object

{
  "id": "job_01HXY8N1K9PZ3R…",
  "title": "Senior Backend Engineer",
  "description": "Build the Qudra matching pipeline…",
  "city": "Riyadh",
  "employment_type": "full_time",
  "salary_min": 18000,
  "salary_max": 30000,
  "currency": "SAR",
  "status": "active",
  "embedding_status": "ready",
  "match_ready": true,
  "qudra_url": "https://qudrah.io/jobs/senior-backend-engineer-01hxy…",
  "created_at": "2026-05-21T08:14:22.123Z",
  "updated_at": "2026-05-21T08:14:54.802Z"
}
FieldTypeDescription
idstringStable Qudra-issued id. Prefixed `job_`.
titlestring3–200 chars. Used in matching — be specific.
descriptionstringUp to 20,000 chars. Markdown is rendered on the public page.
citystringKSA city in English (Riyadh, Jeddah, Dammam, NEOM, …).
employment_typeenum`full_time` · `part_time` · `contract` · `internship`.
salary_minintegerMonthly SAR. Required for full_time and contract.
salary_maxintegerMonthly SAR. Must be ≥ salary_min.
currencystringAlways `SAR` today. Reserved for future expansion.
statusenum`active` · `paused` · `closed`.
embedding_statusenum`processing` · `ready` · `failed`.
match_readyboolean`true` once embedding is ready and the job is in the match graph.
qudra_urlstringPublic canonical URL on qudrah.io.

Create

POST/v1/partner/jobs

Counts against your monthly quota and per-minute rate limit. The embedding runs asynchronously — listen for job.created and job.matched webhooks rather than polling.

Request

curl -X POST https://api.qudrah.io/v1/partner/jobs \
  -H "Authorization: Bearer $QUDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Backend Engineer",
    "description": "Build the Qudra matching pipeline. Stack: NestJS, Postgres, pgvector, Redis.",
    "city": "Riyadh",
    "employment_type": "full_time",
    "salary_min": 18000,
    "salary_max": 30000,
    "currency": "SAR"
  }'

Response — 201 Created

{
  "id": "job_01HXY8N1K9PZ3R…",
  "status": "active",
  "embedding_status": "processing",
  "match_ready": false,
  "qudra_url": "https://qudrah.io/jobs/senior-backend-engineer-01hxy…",
  "created_at": "2026-05-21T08:14:22.123Z"
}

Idempotency

Pass Idempotency-Key: <uuid> to safely retry a create. We deduplicate by hash of (partnerId, idempotencyKey) for 24 hours.

List

GET/v1/partner/jobs

Query params

FieldTypeDescription
limitinteger1–100. Default 20.
cursorstringOpaque cursor from previous response.
statusenumFilter by `active` · `paused` · `closed`.
citystringFilter by city.

Response

{
  "data": [
    { "id": "job_01HXY…", "title": "…", "status": "active", "match_ready": true, "…": "…" }
  ],
  "next_cursor": "eyJpZCI6Imp…",
  "has_more": true
}

Retrieve

GET/v1/partner/jobs/:id

Returns the full job object. Returns 404 partner.not_found if the job doesn't belong to your partner.

Update

PATCH/v1/partner/jobs/:id

Send only the fields you want to change. Updating title or description re-runs the embedding pipeline and temporarily flips match_ready to false.

curl -X PATCH https://api.qudrah.io/v1/partner/jobs/job_01HXY… \
  -H "Authorization: Bearer $QUDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Delete

DELETE/v1/partner/jobs/:id

Soft-deletes the job: it disappears from the seeker feed and matching graph immediately, but we retain it for 30 days for audit. Returns 204 No Content.

Bulk

POST/v1/partner/jobs/bulk

Growth and Scale plans only. Create up to 100 jobs in a single request. Counts as one request against your rate limit but N against your monthly job quota.

Request

curl -X POST https://api.qudrah.io/v1/partner/jobs/bulk \
  -H "Authorization: Bearer $QUDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      { "title": "Backend Engineer",  "city": "Riyadh", "employment_type": "full_time", "salary_min": 15000, "salary_max": 22000 },
      { "title": "Frontend Engineer", "city": "Jeddah", "employment_type": "full_time", "salary_min": 14000, "salary_max": 20000 }
    ]
  }'

Response — 207 Multi-Status

{
  "created": [
    { "index": 0, "id": "job_01HXY…", "status": "active" },
    { "index": 1, "id": "job_01HXZ…", "status": "active" }
  ],
  "errors": []
}

Per-item failures are reported in errors with the same shape as a top-level validation error — the rest of the batch still succeeds.