Jobs

Base URL: /v1

---

Jobs

List Jobs

GET /v1/jobs

Returns a cursor-paginated list of job postings in descending order (newest first).

Authentication: None (public)

Query Parameters

Parameter	Type	Required	Default	Description
type	string	No	—	Filter by job type (e.g., full-time, contract).
status	string	No	—	Filter by job status (e.g., open, closed).
cursor	string	No	—	Cursor token for pagination. Obtained from next_cursor.
limit	number	No	20	Number of results per page. Min 1, max 50.

Response 200 OK

{
  "jobs": [
    {
      "id": "job_abc123",
      "title": "Senior Frontend Engineer",
      "description": "We are looking for an experienced frontend engineer...",
      "type": "full-time",
      "status": "open",
      "location": "Remote",
      "salary_min": 120000,
      "salary_max": 160000,
      "company": "Acme Corp",
      "user_id": "usr_poster01",
      "created_at": "2026-03-28T14:00:00Z",
      "poster": {
        "id": "usr_poster01",
        "username": "acme_hr",
        "first_name": "Morgan",
        "last_name": "Taylor",
        "avatar_url": "https://cdn.example.com/avatars/acme_hr.jpg"
      }
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0yOFQxNDowMDowMFoifQ=="
}

Field	Type	Description
jobs	array	Array of job objects.
jobs[].id	string	Unique job identifier.
jobs[].title	string	Job title.
jobs[].description	string	Full job description.
jobs[].type	string	Job type (e.g., full-time, part-time, contract).
jobs[].status	string	Job status (e.g., open, closed).
jobs[].location	string	Job location or "Remote".
jobs[].salary_min	number | null	Minimum salary. null if not specified.
jobs[].salary_max	number | null	Maximum salary. null if not specified.
jobs[].company	string	Company name.
jobs[].user_id	string	ID of the user who posted the job.
jobs[].created_at	string	ISO 8601 creation timestamp.
jobs[].poster	object	Embedded poster profile.
next_cursor	string | null	Cursor for the next page. null if no more results.

---

Create Job

POST /v1/jobs

Creates a new job posting.

Authentication: Required

Request Body

Field	Type	Required	Description
title	string	Yes	Job title.
description	string	Yes	Full job description.
type	string	No	Job type (e.g., full-time, part-time, contract).
location	string	No	Job location.
salary_min	number	No	Minimum salary.
salary_max	number	No	Maximum salary.
company	string	No	Company name.

Request Example

{
  "title": "Senior Frontend Engineer",
  "description": "We are looking for an experienced frontend engineer to join our team...",
  "type": "full-time",
  "location": "Remote",
  "salary_min": 120000,
  "salary_max": 160000,
  "company": "Acme Corp"
}

Response 201 Created

{
  "job": {
    "id": "job_abc123",
    "title": "Senior Frontend Engineer",
    "description": "We are looking for an experienced frontend engineer to join our team...",
    "type": "full-time",
    "status": "open",
    "location": "Remote",
    "salary_min": 120000,
    "salary_max": 160000,
    "company": "Acme Corp",
    "user_id": "usr_poster01",
    "created_at": "2026-03-28T14:00:00Z"
  }
}

Error Responses

Status	Description
401	Unauthorized. Token missing or invalid.
422	Validation error. Missing title or description.

---

Get Job

GET /v1/jobs/{id}

Returns full details for a single job posting, including the poster profile.

Authentication: None (public)

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The job ID.

Response 200 OK

{
  "job": {
    "id": "job_abc123",
    "title": "Senior Frontend Engineer",
    "description": "We are looking for an experienced frontend engineer to join our team...",
    "type": "full-time",
    "status": "open",
    "location": "Remote",
    "salary_min": 120000,
    "salary_max": 160000,
    "company": "Acme Corp",
    "user_id": "usr_poster01",
    "created_at": "2026-03-28T14:00:00Z",
    "poster": {
      "id": "usr_poster01",
      "username": "acme_hr",
      "first_name": "Morgan",
      "last_name": "Taylor",
      "avatar_url": "https://cdn.example.com/avatars/acme_hr.jpg"
    }
  }
}

Error Responses

Status	Description
404	Job not found.

---

Update Job

PATCH /v1/jobs/{id}

Updates an existing job posting. Only the job owner can update it. All fields are optional — only provided fields are updated.

Authentication: Required (owner only)

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The job ID.

Request Body

Field	Type	Required	Description
title	string	No	Updated job title.
description	string	No	Updated job description.
type	string	No	Updated job type.
location	string	No	Updated location.
salary_min	number	No	Updated minimum salary.
salary_max	number	No	Updated maximum salary.
company	string	No	Updated company name.
status	string	No	Updated status (e.g., open, closed).

Request Example

{
  "salary_max": 180000,
  "status": "closed"
}

Response 200 OK

{
  "job": {
    "id": "job_abc123",
    "title": "Senior Frontend Engineer",
    "description": "We are looking for an experienced frontend engineer to join our team...",
    "type": "full-time",
    "status": "closed",
    "location": "Remote",
    "salary_min": 120000,
    "salary_max": 180000,
    "company": "Acme Corp",
    "user_id": "usr_poster01",
    "created_at": "2026-03-28T14:00:00Z"
  }
}

Error Responses

Status	Description
401	Unauthorized. Token missing or invalid.
403	Forbidden. Caller is not the job owner.
404	Job not found.

---

Delete Job

DELETE /v1/jobs/{id}

Permanently deletes a job posting. Only the job owner can delete it.

Authentication: Required (owner only)

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The job ID.

Response 200 OK

{
  "message": "Job deleted successfully."
}

Error Responses

Status	Description
401	Unauthorized. Token missing or invalid.
403	Forbidden. Caller is not the job owner.
404	Job not found.

---

Apply to Job

POST /v1/jobs/{id}/apply

Submits an application for a job posting.

Authentication: Required

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The job ID.

Request Body

Field	Type	Required	Description
cover_letter	string	No	Cover letter text.
resume_url	string	No	URL to the applicant’s resume file.

Request Example

{
  "cover_letter": "I am excited to apply for this position. With 5 years of frontend experience...",
  "resume_url": "https://cdn.example.com/resumes/taylor-brooks-resume.pdf"
}

Response 201 Created

{
  "application": {
    "id": "app_xyz789",
    "job_id": "job_abc123",
    "user_id": "usr_applicant01",
    "cover_letter": "I am excited to apply for this position. With 5 years of frontend experience...",
    "resume_url": "https://cdn.example.com/resumes/taylor-brooks-resume.pdf",
    "created_at": "2026-03-30T09:00:00Z"
  }
}

Field	Type	Description
application.id	string	Unique application identifier.
application.job_id	string	The job this application is for.
application.user_id	string	The applicant’s user ID.
application.cover_letter	string	Submitted cover letter text.
application.resume_url	string	URL to the submitted resume.
application.created_at	string	ISO 8601 creation timestamp.

Error Responses

Status	Description
401	Unauthorized. Token missing or invalid.
404	Job not found.