# softon.dev

> Independent data APIs behind one account, one key and one response envelope. Job postings and events, scraped from source, served over a documented HTTP API.

All responses share the shape `{ data, meta, error }`. Collections are cursor-paginated: follow `meta.next` until it is null. Authenticate with `Authorization: Bearer <key>` on every request. Base URL: https://api.softon.dev/v1

## Datasets

### Job Data API (live)

Postings from company career pages and boards, deduplicated per source, with the source's own employment type, job function and career level preserved rather than mapped to a taxonomy that would hide disagreements.

- `GET /v1/jobs` — List job postings: https://softon.dev/docs/jobs/list-jobs
- `GET /v1/jobs/{id}` — Retrieve a job: https://softon.dev/docs/jobs/get-job
- `POST /v1/jobs/liveness` — Batch liveness: https://softon.dev/docs/jobs/job-liveness
- `GET /v1/companies/{id}/jobs` — Company jobs: https://softon.dev/docs/jobs/list-company-jobs

Fields: id, source, source_name, source_url, title, company, location, city, district, country, remote, employment_type, job_function, career_level, salary_from, salary_to, salary_currency, salary_period, deadline_at, posted_at, url, description, requirements, facts, ingested_at, first_seen_at, times_seen, active, deactivated_at, work_type, company_logo, view_count, contact_email, contact_phone

### Event Data API (live)

Concerts, theatre, exhibitions and cinema with geocoded venues and UTC instants for every time. Where the source publishes per-showing ticket inventory it is recorded at every scrape, so successive scrapes give you sell-through rather than a snapshot.

- `GET /v1/events` — List events: https://softon.dev/docs/events/list-events
- `GET /v1/events/{id}` — Retrieve an event: https://softon.dev/docs/events/get-event
- `GET /v1/venues/{id}` — Retrieve a venue: https://softon.dev/docs/events/get-venue

Fields: id, source, slug, name, category, venue, starts_at, ends_at, price, age_limit, tickets_available, description, url, external_url, poster_url, ingested_at

### Quotes Data API (live)

Attributed quotations with author, category and the collection each was gathered from. Only the active pool is served -- the upstream's own judgement about what is fit to show -- and the quote-of-the-day endpoint is deterministic for a given UTC date, so one call a day is enough.

- `GET /v1/quotes` — List quotations: https://softon.dev/docs/quotes/list-quotes
- `GET /v1/quotes/{id}` — Retrieve a quotation: https://softon.dev/docs/quotes/get-quote
- `GET /v1/quotes/random` — Quote of the day: https://softon.dev/docs/quotes/get-random-quote

Fields: id, source, text, author, category, origin, ingested_at

### Rates Data API (live)

The Central Bank of Azerbaijan's official daily bulletin: 38 currencies and 4 bank metals against the manat. Every row carries the date you asked for AND the date the bank published, so a weekend's repeated numbers are marked as repeats — and rate_per_unit is value divided by nominal, which matters for the seven currencies quoted per 100. Dates are Asia/Baku. Attribution, if you publish these numbers: “Mənbə: Azərbaycan Respublikasının Mərkəzi Bankı” (Source: the Central Bank of the Republic of Azerbaijan), cbar.az.

- `GET /v1/rates` — List exchange rates: https://softon.dev/docs/rates/list-rates
- `GET /v1/rates/latest` — Latest bulletin: https://softon.dev/docs/rates/get-latest-rates
- `GET /v1/rates/{id}` — Retrieve a rate: https://softon.dev/docs/rates/get-rate

Fields: id, source, date, effective_date, carried_forward, kind, base, code, name, unit, nominal, value, rate_per_unit, source_url, bulletin_url, ingested_at

### Genome Source Releases API (live)

What release each upstream genome data source is on, and when we last managed to read it. Four sources today — RefSeq, dbSNP, 1000 Genomes/IGSR and NCBI Datasets — each probed once a day and read from the source itself rather than hardcoded. Release markers only: no sequence, no assembly, no annotation and no variant data is served here or held behind it. Every row carries the probe's own verdict next to the version, because a version number alone cannot tell a release that has not moved from a probe that has stopped working — IGSR's newest data freeze really is from 2013, and dbSNP's marker used to be read off a single variant record, which is a number that can freeze without anything saying so.

- `GET /v1/genome/releases` — List genome source releases: https://softon.dev/docs/genome/list-genome-releases
- `GET /v1/genome/releases/{id}` — Retrieve one genome source release: https://softon.dev/docs/genome/get-genome-release

Fields: id, source, source_id, source_name, authority, category, landing_url, api_url, bulk_url, update_frequency, release_version, release_date, checksum, format, retrieved_at, status, extra, sort_order, ingested_at

### Reachability API (live)

Whether a watched URL answered us, why not if it did not, and how long it has been that way. Six targets today, probed once a day. No page content is read, stored or served here — a status code is a fact about a request we made, which is also why this is the one dataset on this platform with nothing to license. A false “reachable” is not a claim that a site is down: two of these six sit behind bot protection that answers our client a challenge page rather than the site, and which answer we get has been measured changing with nothing but the HTTP version we negotiated. So every row carries the class of failure, the vantage the request left from, and the number of consecutive probes that have failed — because one refusal is noise and sixty-one in a row is a finding.

- `GET /v1/reachability` — List watched targets and how each one last answered: https://softon.dev/docs/reachability/list-reachability
- `GET /v1/reachability/{id}` — Retrieve one watched target: https://softon.dev/docs/reachability/get-reachability

Fields: id, source, target_id, url, watchlist, vantage, reachable, http_status, final_url, redirected, failure_class, error, response_ms, robots_allowed, checked_at, last_reachable_at, first_failed_at, consecutive_failures, ingested_at

## Written

- [The Azerbaijan jobs API](https://softon.dev/azerbaijan-jobs-api): Every job posting from Azerbaijani boards and company career pages, scraped three times a day and served as JSON behind one key. Documented from the API's own schema, with the gaps stated rather than filled in.
- [A dead source and a quiet one look identical from the outside](https://softon.dev/blog/a-dead-source-and-a-quiet-one), 2026-08-31: Seven job boards stopped answering us in the same week. Telling that apart from seven boards that simply had nothing to post is most of what an is_active field is worth.
- [Why a job's city is a closed vocabulary](https://softon.dev/blog/a-city-you-can-filter-on), 2026-08-24: The location a source publishes is a string. Turning it into something you can filter on meant deciding, once, that a name no source emits is a name that cannot arrive.
- [Atom feed](https://softon.dev/blog/feed.xml): new posts, machine-readable.

## Reference

- [Quickstart](https://softon.dev/docs/shared/quickstart): Sign up, copy the key, call the endpoint. Three minutes to the first row.
- [Authentication](https://softon.dev/docs/shared/authentication): One page, shared by every dataset. Send your key as a bearer token on every request.
- [Rate limits & quotas](https://softon.dev/docs/shared/limits): Every response carries your current budget, so a client can back off before it is refused rather than after.
- [Pagination & errors](https://softon.dev/docs/shared/errors): Cursor pagination and the same error codes on every dataset.
- [Data freshness](https://softon.dev/docs/shared/freshness): When each dataset is scraped, in UTC, and what changes on a row when it is seen again.
- [Our crawler](https://softon.dev/docs/shared/crawler): What SoftonBot is, which sites it visits, and how to tell it not to.
- [Acceptable use](https://softon.dev/docs/shared/use): What you may do with the data you pull, how long you may keep it, and the one thing we ask you to pass on.
- [Versioning & changes](https://softon.dev/docs/shared/versioning): What "v1 · stable" commits to, what counts as a breaking change, how much notice you get, and everything that has changed so far.
- [Response envelope](https://softon.dev/docs/shared/envelope): the three top-level keys every response carries.
- [Machine-readable schema](https://api.softon.dev/v1/schema): the published contract, generated from the serving code.

## Notes

- Fields are documented from the API's own published schema, not written by hand. A field listed here is a field the API returns.
- A value the source does not publish is `null`, never a placeholder or a zero.
- Timestamps are RFC 3339 instants in UTC.