Skip to content
agent-data

Create Search Job

POST
/v1/search-jobs
 
agent-data call f9a6ec16-0bfd-44d8-b3ee-073776745ee7 search-jobs --keywords <keywords> [--location New York] [--limit <limit>] [--fields <fields>] [--source <source>]

Single-source job search. Every request targets exactly one source: linkedin, ashby, greenhouse, lever. If source is omitted the API defaults to linkedin. This route never fans out across multiple sources. LinkedIn searches live upstream; Ashby, Greenhouse, and Lever search the service-refreshed local postings store. Returns up to limit summary rows matching the keywords (+ optional location) query. Each row carries an id (format jp_<12-hex>) AND a source_url — keep BOTH; you’ll need them as a pair when calling get-posting. Use fields=id,title,company_name (comma-separated) to request a subset of fields and reduce response size. Allowed fields: [‘capture_method’, ‘company_name’, ‘department_name’, ‘detail_available’, ‘employment_type’, ‘id’, ‘is_remote’, ‘location_display’, ‘missing_fields’, ‘posted_at’, ‘published_at’, ‘salary_display’, ‘search_status’, ‘source’, ‘source_id’, ‘source_url’, ‘staleness_status’, ‘team_name’, ‘title’, ‘workplace_type’]. Errors: 422 validation_error (param fails type/range validation; details[].loc identifies the field); 400 validation_error (fields= or source= violates the request contract); 503 upstream_unavailable (the chosen upstream source failed, retryable:true — caller decides backoff).

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
keywords
required
Keywords

Search query terms. Required.

string
>= 1 characters

Search query terms. Required.

location
Any of:
string

Optional location filter, e.g. New York. Accepts a city, state/region, or country (names, common aliases like NYC/SF, ISO codes like US/GBR, and native spellings like München all resolve via GeoNames). linkedin: forwarded to LinkedIn’s own location filter. ashby/greenhouse/lever: matched against each posting’s resolved location with hierarchical containment — a country matches every city in it. ‘Remote’ matches remote-flagged postings. Unrecognized strings fall back to substring match on the posting’s displayed location. Qualify ambiguous cities (‘London, UK’).

limit
Limit

Maximum number of results to return (1-100).

integer
default: 20 >= 1 <= 100

Maximum number of results to return (1-100).

fields
Any of:
string

Optional comma-separated list of fields to include per row. Allowed: [‘capture_method’, ‘company_name’, ‘department_name’, ‘detail_available’, ‘employment_type’, ‘id’, ‘is_remote’, ‘location_display’, ‘missing_fields’, ‘posted_at’, ‘published_at’, ‘salary_display’, ‘search_status’, ‘source’, ‘source_id’, ‘source_url’, ‘staleness_status’, ‘team_name’, ‘title’, ‘workplace_type’].

source
Any of:
string

Single source to search. Allowed: linkedin, ashby, greenhouse, lever. Omitted defaults to linkedin. Comma-separated or repeated values are rejected with 400 validation_error; this route never fans out across sources.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Search results.

Media type application/json
SearchJobApiResponse
object
data
required
SearchJobData
object
query
required
SearchJobQuery
object
source
required
Source
string
keywords
required
Keywords
string
location
Any of:
string
status
required
Status
string
results
required
Results
Array<object>
SearchJobRow

One row in a search-jobs result. All fields optional because sparse fieldsets (?fields=id,title) may omit any subset.

object
id
Any of:
string
title
Any of:
string
source
Any of:
string
is_remote
Any of:
boolean
posted_at
Any of:
string format: date-time
source_id
Any of:
string
team_name
Any of:
string
source_url
Any of:
string
company_name
Any of:
string
published_at
Any of:
string format: date-time
search_status
Any of:
string
capture_method
Any of:
string
missing_fields
Any of:
Array<string>
salary_display
Any of:
string
workplace_type
Any of:
string
department_name
Any of:
string
employment_type
Any of:
string
detail_available
Any of:
boolean
location_display
Any of:
string
staleness_status
Any of:
string
warnings
required
Warnings
Array<string>
started_at
required
Started At
string format: date-time
completed_at
required
Completed At
string format: date-time
meta
required
SearchJobMeta
object
request_id
required
Request Id
string
Example generated
{
  "data": {
    "query": {
      "source": "example",
      "keywords": "example",
      "location": "example"
    },
    "status": "example",
    "results": [
      {
        "id": "example",
        "title": "example",
        "source": "example",
        "is_remote": true,
        "posted_at": "2026-04-15T12:00:00Z",
        "source_id": "example",
        "team_name": "example",
        "source_url": "example",
        "company_name": "example",
        "published_at": "2026-04-15T12:00:00Z",
        "search_status": "example",
        "capture_method": "example",
        "missing_fields": [
          "example"
        ],
        "salary_display": "example",
        "workplace_type": "example",
        "department_name": "example",
        "employment_type": "example",
        "detail_available": true,
        "location_display": "example",
        "staleness_status": "example"
      }
    ],
    "warnings": [
      "example"
    ],
    "started_at": "2026-04-15T12:00:00Z",
    "completed_at": "2026-04-15T12:00:00Z"
  },
  "meta": {
    "request_id": "example"
  }
}

400

Section titled “400 ”

Service-side request contract error. error.param identifies the offending field when available.

Media type application/json
ErrorResponse
object
error
required
ErrorBody
object
body
Any of:
Body
code
required
Code
string
param
Any of:
string
source
Source
string
default: service
Allowed values: upstream gateway cli aws_authorizer service client
status
required
Status
integer
details
Any of:
Array<object>
object
key
additional properties
any
message
required
Message
string
retryable
required
Retryable
boolean
request_id
required
Request Id
string
Example 
{
  "error": {
    "source": "upstream"
  }
}

422

Section titled “422 ”

Client validation error. details[] identifies the offending field.

Media type application/json
ErrorResponse
object
error
required
ErrorBody
object
body
Any of:
Body
code
required
Code
string
param
Any of:
string
source
Source
string
default: service
Allowed values: upstream gateway cli aws_authorizer service client
status
required
Status
integer
details
Any of:
Array<object>
object
key
additional properties
any
message
required
Message
string
retryable
required
Retryable
boolean
request_id
required
Request Id
string
Example 
{
  "error": {
    "source": "upstream"
  }
}

503

Section titled “503 ”

Upstream dependency unavailable (retryable:true). The caller decides retry cadence.

Media type application/json
ErrorResponse
object
error
required
ErrorBody
object
body
Any of:
Body
code
required
Code
string
param
Any of:
string
source
Source
string
default: service
Allowed values: upstream gateway cli aws_authorizer service client
status
required
Status
integer
details
Any of:
Array<object>
object
key
additional properties
any
message
required
Message
string
retryable
required
Retryable
boolean
request_id
required
Request Id
string
Example 
{
  "error": {
    "source": "upstream"
  }
}