Attia-API-et

Oversikt⁠

Med Attia-API-et kan dine egne programmer lese data fra et arbeidsområde over HTTPS. Alle adresser starter med https://attia.app/api/v1, alle svar er JSON, og en personlig API-nøkkel viser hvem du er.

Versjon 1 har én operasjon foreløpig, List jobber. Denne siden dekker det som er felles for alle operasjoner.

Autentisering⁠

Opprett en nøkkel under Innstillinger → Sikkerhet og tilgang → Personlige API-nøkler, med minst tillatelsen Lese. Attia viser nøkkelen én gang, så kopier den da. En nøkkel starter med attia_api_.

Nøkkelen handler som deg. Den leser det du selv kan lese i arbeidsområdet, og ikke mer enn tillatelsene og teamene du ga den. Tilbakekaller du nøkkelen på samme side, slutter den å virke med en gang.

Send nøkkelen i Authorization-headeren som et bearer-token. Nøkkelen alene, uten Bearer, virker også.

curl https://attia.app/api/v1/jobs \  -H "Authorization: Bearer $ATTIA_API_KEY"

Kall API-et fra en server eller et skript, aldri fra en nettside. API-et sender ingen CORS-headere, så nettleseren avviser svaret, og en nøkkel i kildekoden til en side kan hvem som helst kopiere.

Hvis arbeidsområdet begrenser tilgang etter IP-adresse, gjelder den samme listen for API-kall. Et kall fra en annen adresse får ip-not-allowed. Eiere av arbeidsområdet er unntatt, slik de er i appen.

Ditt første kall⁠

Legg nøkkelen i en miljøvariabel og be om to jobber.

export ATTIA_API_KEY="attia_api_..." curl "https://attia.app/api/v1/jobs?limit=2" \  -H "Authorization: Bearer $ATTIA_API_KEY"

En liste svarer med data og next_cursor.

{  "data": [    {      "id": "0192f3a1-6b02-7d4c-8e11-5a9c0b7d3e01",      "title": "Backend-utvikler",      "slug": "backend-utvikler",      "status": "live",      "team_id": "0192f39f-11aa-7c3e-b2d4-9e8f7a6b5c4d",      "employment_type": "full_time",      "contract_type": "permanent",      "workplace_type": "hybrid",      "locations": ["Eksempelvik"],      "positions_count": 2,      "application_deadline": "2026-11-15",      "published_at": "2026-09-28T07:30:00.000000Z",      "closed_at": null,      "archived_at": null,      "created_at": "2026-09-25T12:04:51.220417Z",      "updated_at": "2026-10-01T09:42:10.118305Z"    },    {      "id": "0192f3a1-7c44-7b1e-9a50-3f1d2c6e8a02",      "title": "Butikksjef",      "slug": "butikksjef",      "status": "draft",      "team_id": "0192f39f-11aa-7c3e-b2d4-9e8f7a6b5c4d",      "employment_type": "part_time",      "contract_type": "temporary",      "workplace_type": "onsite",      "locations": [],      "positions_count": 1,      "application_deadline": null,      "published_at": null,      "closed_at": null,      "archived_at": null,      "created_at": "2026-10-02T08:15:30.482913Z",      "updated_at": "2026-10-02T08:15:30.482913Z"    }  ],  "next_cursor": "eyJ1IjoiMjAyNi0xMC0wMlQwODoxNTozMC40ODI5MTNaIiwiaSI6IjAxOTJmM2ExLTdjNDQtN2IxZS05YTUwLTNmMWQyYzZlOGEwMiJ9"}

Paginering⁠

En liste gir 25 elementer hvis du ikke setter limit, som tar 1 til 100. Finnes det flere, inneholder next_cursor en streng. Send den tilbake som cursor for å få neste side, og stopp når next_cursor er null.

curl "https://attia.app/api/v1/jobs?limit=2&cursor=eyJ1IjoiMjAyNi0xMC0wMlQwODoxNTozMC40ODI5MTNaIiwiaSI6IjAxOTJmM2ExLTdjNDQtN2IxZS05YTUwLTNmMWQyYzZlOGEwMiJ9" \  -H "Authorization: Bearer $ATTIA_API_KEY"

Behandle en cursor som en ugjennomsiktig streng. Ikke bygg en selv, og ikke endre den.

Alle lister sorterer etter updated_at, eldste først, og deretter etter id. Den rekkefølgen holder en cursor stabil mens folk redigerer. Et element som blir redigert mens du leser, flytter seg bak cursoren, og du kan få det igjen på en senere side. Regn med å få et element to ganger av og til, og bruk id som nøkkel. En gjennomgang kan likevel gå glipp av en endring som lagres mens du leser, så hent endringer jevnlig slik neste avsnitt beskriver.

updated_since gir bare elementer som er oppdatert på eller etter et tidspunkt. Grensen er inkluderende, så et element oppdatert på nøyaktig det tidspunktet kommer med. Vil du hente endringer jevnlig, tar du vare på den største updated_at du har sett og sender et tidspunkt fem minutter før den som updated_since neste gang. En endring får sin updated_at når lagringen starter. En lagring som blir ferdig etter at du hentet, kan derfor ha et tidspunkt som er eldre enn et du allerede har lest. De fem minuttene med overlapp er der for å fange opp slike endringer. Du får også elementer du allerede har, så fjern gjentakelsene etter id.

Tidsstempler, null og enum-verdier⁠

Et tidsstempel er en streng i UTC, i RFC 3339-form med mikrosekunder og Z, for eksempel 2026-10-02T08:15:30.482913Z. Et felt som holder en kalenderdag uten klokkeslett, som application_deadline, er YYYY-MM-DD.

Et tidsstempel du sender, som updated_since, trenger Z eller en tidsforskyvning. Skriv + i en tidsforskyvning som %2B, for en + alene betyr mellomrom i en URL.

curl "https://attia.app/api/v1/jobs?updated_since=2026-10-01T00:00:00Z" \  -H "Authorization: Bearer $ATTIA_API_KEY"

Et felt uten verdi er med i svaret og er null. API-et utelater aldri et felt, så sjekk for null og ikke for at nøkkelen mangler. En tom liste er [].

En enum-verdi er en streng med små bokstaver, som live eller full_time. Versjon 1 kan legge til en verdi, så koden din må tåle en verdi den ikke kjenner.

Feil⁠

En feil svarer med den passende HTTP-statusen og et problemdokument etter RFC 9457. Innholdstypen er application/problem+json.

curl -i https://attia.app/api/v1/jobs \  -H "Authorization: Bearer attia_api_not_a_real_key"

{  "type": "https://attia.app/docs/api#invalid-api-key",  "title": "Invalid API key",  "status": 401,  "detail": "The request has no API key, or the key is unknown, revoked or expired.",  "code": "invalid-api-key"}

Bruk code i koden din. Den endrer seg aldri. title og detail er skrevet for mennesker, alltid på engelsk, og kan få ny ordlyd. type lenker til kodens avsnitt nedenfor.

invalid-api-key⁠

Status 401. Forespørselen mangler nøkkel, nøkkelen er feilskrevet, eller den er ukjent, tilbakekalt eller utløpt. Opprett en ny nøkkel og send den i Authorization-headeren.

insufficient-scope⁠

Status 403. Nøkkelen er gyldig, men mangler tillatelsen operasjonen krever. Lesing krever Lese. Opprett en nøkkel som har den.

ip-not-allowed⁠

Status 403. Arbeidsområdet begrenser tilgang etter IP-adresse, og kallet kom fra en adresse utenfor listen. Kall fra en adresse på listen, eller be en administrator i arbeidsområdet om å legge til din.

invalid-request⁠

Status 400. En spørreparameter er ukjent, gjentatt eller har en verdi API-et ikke godtar. errors navngir hver av dem.

{  "type": "https://attia.app/docs/api#invalid-request",  "title": "Invalid request",  "status": 400,  "detail": "One or more parameters are not valid.",  "code": "invalid-request",  "errors": [{ "field": "limit", "message": "Must be an integer from 1 to 100." }]}

rate-limited⁠

Status 429. Du har sendt for mange forespørsler. Vent så mange sekunder som Retry-After-headeren sier, og prøv igjen. Se Rategrenser.

api-unavailable⁠

Status 503. API-et er slått av eller kan ikke nås akkurat nå. Prøv igjen senere.

internal-error⁠

Status 500. Noe feilet hos oss, og vi har fått en rapport om det. Det kan hjelpe å prøve igjen. Hvis feilen fortsetter, kontakt support.

Rategrenser⁠

Hvert medlem av et arbeidsområde kan sende 2 500 forespørsler i timen, talt på tvers av alle nøklene til medlemmet, og ikke flere enn 10 i ett sekund. Et 200-svar har tre headere, og det har også et 403-svar med ip-not-allowed. Ingen andre feil har dem.

curl -s -o /dev/null -D - https://attia.app/api/v1/jobs \  -H "Authorization: Bearer $ATTIA_API_KEY" | grep -i x-ratelimit

x-ratelimit-requests-limit: 2500x-ratelimit-requests-remaining: 2487x-ratelimit-requests-reset: 1791637200000

Over grensen svarer API-et 429 med Retry-After i sekunder. Vent så lenge før neste forespørsel. For å holde deg under grensen blar du med så stor limit som du kan bruke, og henter endringer med updated_since.

Versjonering og utfasing⁠

Versjonen står i stien, /api/v1. Versjon 1 vokser bare. Vi kan legge til en operasjon, et felt i et svar, en valgfri parameter eller en enum-verdi, så se bort fra felt du ikke kjenner. Vi fjerner ikke et felt, gir det ikke nytt navn, endrer ikke en type og gjør ikke en valgfri parameter påkrevd. En slik endring ville blitt en versjon 2 på en ny sti.

Før en operasjon fases ut, har svarene en Deprecation-header med datoen den ble markert som utgående, og en Sunset-header med datoen den slutter å virke. Logg disse headerne i klienten din, så en utfasing ikke kommer overraskende.

OpenAPI 3.1-beskrivelsen av versjon 1 er åpen, og du kan generere en klient fra den.

curl https://attia.app/api/v1/openapi.json