App: Jobs

The Jobs endpoints let you queue candidate searches as async background jobs and poll their status. Use these when a search may take longer than a synchronous request allows. After starting a job, poll its status — or long-poll with wait=done to block until completion.

---

Start an async search job

POST /api/v1/run/search/jobs

Queues a candidate search in the background and returns a job handle that can be polled through the jobs endpoint.

cURL

curl -X POST "https://api.hoody.com/api/v1/run/search/jobs" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "firefox",
    "os": "linux",
    "kind": "gui"
  }'

TypeScript SDK

import { Hoody } from "@hoody/sdk";

const client = new Hoody({ apiKey: process.env.HOODY_API_KEY });

const { data: job } = await client.app.jobs.createSearch({
  app: "firefox",
  os: "linux",
  kind: "gui",
});

console.log(job.job_id);

This endpoint takes no parameters.

Request Body

The request body is a JSON object conforming to the app_Selector schema. The only required field is app (the primary name query). All other fields are optional and control filtering, execution context, and output format.

{
  "app": "firefox",
  "os": "linux",
  "kind": "gui"
}

Response

202

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "search-resolve",
  "status": "queued",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

400

{
  "error": "missing app",
  "code": 400
}

503

{
  "error": "Job scheduler unavailable, please retry",
  "code": 503
}

---

Get job status

GET /api/v1/run/jobs/{job_id}

Retrieves the current status of an async background job. Supports long-polling with wait=done to block until the job completes or a timeout is reached.

Parameters

Name	In	Type	Required	Description
job_id	path	string	Yes	Job identifier (UUID)
wait	query	string	No	Set to 'done' to long-poll until job completes
timeout_ms	query	integer	No	Long-poll timeout in milliseconds (default 0, max 120000)

cURL

curl "https://api.hoody.com/api/v1/run/jobs/550e8400-e29b-41d4-a716-446655440000?wait=done&timeout_ms=30000" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { Hoody } from "@hoody/sdk";

const client = new Hoody({ apiKey: process.env.HOODY_API_KEY });

const { data: status } = await client.app.jobs.getStatus(
  "550e8400-e29b-41d4-a716-446655440000",
  { wait: "done", timeout_ms: 30000 },
);

console.log(status.status);

This endpoint accepts no request body.

Response

200

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "search-resolve",
  "status": "done",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:05Z",
  "result_type": "search-response",
  "result": {
    "candidates": []
  }
}

404

{
  "error": "No job exists with the requested identifier",
  "code": 404
}

Error Code	Title	Description	Resolution
JOB_NOT_FOUND	Job not found	No job exists with the requested identifier	Use the job_id returned by syncSource or syncAllSources

Job object fields

The app_Job object returned on 200 and 202 responses contains the following fields:

Field	Type	Required	Description
job_id	string (UUID)	Yes	Unique job identifier
kind	enum	Yes	Job type: source-sync, search-resolve
status	enum	Yes	Current status: queued, running, done, error
created_at	string (date-time)	Yes	ISO 8601 timestamp when the job was created
updated_at	string (date-time)	Yes	ISO 8601 timestamp of the last status change
error	string	No	Error message (present when status is error)
result_type	enum	No	Type of inline job result payload: search-response
result	object	No	Inline job result payload when available
progress	object	No	Optional progress metadata for long-running jobs