Skip to main content

​
Endpoint

POST /jobs

​
Request body

{
  "name": "Q1 Catalog Scan",
  "items": [
    { "item_id": "track-001", "url": "https://cdn.example.com/01.mp3" },
    { "item_id": "track-002", "url": "https://cdn.example.com/02.mp3" }
  ],
  "webhook_url": "https://yourapi.com/webhooks/hs"
}
FieldTypeRequiredDescription
namestringYesHuman-readable label for the job
itemsarrayYes*Array of track items (max 10,000 per request)
manifest_urlstringYes*URL to a NDJSON manifest file for large batches
webhook_urlstringNoEndpoint to receive job.complete and track.complete events
*Provide either items or manifest_url.

​
Item fields

FieldTypeRequiredDescription
item_idstringYesYour identifier — returned in results
urlstringYes*Publicly accessible audio URL
file_idstringYes*File identifier for signed URL resolution
metadataobjectNoArbitrary key-value pairs, returned in results

​
Example request

import requests, os

job = requests.post(
    "https://app.jobsbyhumans.com/api/v1/jobs",
    headers={"Authorization": f"Bearer {os.environ['HS_API_KEY']}"},
    json={
        "name": "Q1 Catalog Scan",
        "items": [
            {"item_id": "track-001", "url": "https://cdn.example.com/01.mp3"},
            {"item_id": "track-002", "url": "https://cdn.example.com/02.mp3"},
        ],
        "webhook_url": "https://yourapi.com/webhooks/hs",
    }
).json()

print(job["id"])     # "job_abc123"
print(job["status"]) # "queued"

​
Response

{
  "id": "job_abc123",
  "name": "Q1 Catalog Scan",
  "status": "queued",
  "total": 2,
  "processed": 0,
  "succeeded": 0,
  "failed": 0,
  "verdict_counts": { "human": 0, "suspicious": 0 },
  "created_at": "2026-02-27T10:00:00Z",
  "completed_at": null
}