REST-API

HIT inkluderar ett REST-API som låter dig utföra vissa åtgärder från ett annat system.

Autentisering

För att använda API:et behöver du först skapa en API-nyckel under Min profil → Säkerhet → API-nycklar.

Behörigheter

API-nycklar har samma behörigheter som användaren som skapade nyckeln. Det går dock att skapa en nyckel med endast läsrättigheter.

Varje API-anrop behöver ha headern Authorization: Bearer <nyckel>:

curl -H 'Authorization: Bearer <apitoken>' https://din-hit-domän/api/queues

Basadressen

Byt ut din-hit-domän mot adressen ni når HIT på — samma värdnamn som i webbläsaren.

Anrop som ska få svar i JSON bör dessutom skicka med headern Accept: application/json.

Lista tillgängliga köer

Metod: GETEndpoint: /api/queues

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' https://din-hit-domän/api/queues

Exempel på svar:

json

{
    "status": "OK",
    "queues": [
        {
            "id": 1,
            "name": "Demoskolan IT"
        },
        {
            "id": 2,
            "name": "Demoskolan Vaktis"
        }
    ]
}

Lista ärenden i en kö

Metod: GETEndpoint: /api/queues/{queueId}/tickets

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' https://din-hit-domän/api/queues/1/tickets

Exempel på svar:

json

{
    "status": "OK",
    "page": 1,
    "limit": 50,
    "tickets_count": 42,
    "tickets": [
        {
            "id": 67,
            "submitter_name": "Robin Friberg",
            "submitter_email": "robin@devpeak.se",
            "subject": "Nothing to see here",
            "date": "2023-07-12T06:04:50.000000Z",
            "closed_date": null
        },
        {
            "id": 66,
            "submitter_name": "Robin Friberg",
            "submitter_email": "robin@devpeak.se",
            "subject": "Other ticket",
            "date": "2023-07-09T08:07:29.000000Z",
            "closed_date": null
        }
    ]
}

Sök efter ärenden i en kö

Metod: GETEndpoint: /api/queues/{queueId}/tickets

Krävda parametrar:

search

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' 'https://din-hit-domän/api/queues/1/tickets?search=Something'

Exempel på svar:

json

{
    "status": "OK",
    "page": 1,
    "limit": 50,
    "tickets_count": 42,
    "tickets": [
        {
            "id": 67,
            "submitter_name": "Robin Friberg",
            "submitter_email": "robin@devpeak.se",
            "subject": "Nothing to see here",
            "date": "2023-07-12T06:04:50.000000Z",
            "closed_date": null
        },
        {
            "id": 66,
            "submitter_name": "Robin Friberg",
            "submitter_email": "robin@devpeak.se",
            "subject": "Other ticket",
            "date": "2023-07-09T08:07:29.000000Z",
            "closed_date": null
        }
    ]
}

Skapa nytt ärende

Metod: POSTEndpoint: /api/queues/{queueId}/tickets

Krävda parametrar:

subject
description

Valfria parametrar:

submitter
submitter_name
notify_submitter
priority
owner
category
customer
status
duedate
hideuntil
files[]

priority är 0–3 (låg till kritisk). owner, category, customer och status måste tillhöra kön. category, customer, status, duedate och hideuntil kräver dessutom att motsvarande modul är påslagen i kön, och varje valfritt fält kräver samma behörighet som att ändra det på ett befintligt ärende.

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -X POST \
  -d 'subject=A well written subject&description=Not so well written description&submitter=reporter@example.com&priority=3&duedate=2026-09-01' \
  https://din-hit-domän/api/queues/1/tickets

Exempel på svar:

json

{
    "status": "OK",
    "message": "Your ticket has been created correctly",
    "ticketid": 73
}

Lista ärendemallar

Metod: GETEndpoint: /api/queues/{queueId}/tickettemplates

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  https://din-hit-domän/api/queues/1/tickettemplates

Exempel på svar:

json

{
    "status": "OK",
    "tickettemplates": [
        {
            "id": 1,
            "name": "A ticket template",
            "description": "Description of the ticket template",
            "template_text": "<p>Some HTML content</p>",
            "subtickets": [
                {
                    "id": 1,
                    "subject": "A subticket for this ticket template",
                    "tickettemplate": 1
                },
                {
                    "id": 2,
                    "subject": "Another subticket for this ticket template",
                    "tickettemplate": 1
                }
            ]
        }
    ]
}

Skapa nya ärenden från en ärendemall

Metod: POSTEndpoint: /api/queues/{queueId}/tickets

Krävda parametrar:

subject
description
template
subtickets

Valfria parametrar:

should_mail — styr handläggarnotisen för huvudärendet. Anges den gäller den även samtliga underärenden, om inte subtickets_mail skickas med. Utelämnas den används mallens egen inställning för huvudärendet respektive varje underärende.
subtickets_mail — kommaseparerad lista med de underärenden som ska ge handläggarnotis. Måste vara en delmängd av subtickets. Underärenden som utelämnas ur listan notifierar inte.

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' -X POST \
  -d 'template=1&subject=New user&description=A new user should be created called Example_User&should_mail=0&subtickets=1,2' \
  https://din-hit-domän/api/queues/1/tickets

Exempel där bara underärende 2 ska notifiera handläggare:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' -X POST \
  -d 'template=1&subject=New user&description=A new user should be created called Example_User&subtickets=1,2&subtickets_mail=2' \
  https://din-hit-domän/api/queues/1/tickets

Exempel på svar:

json

{
    "status": "OK",
    "message": "Your ticket has been created correctly",
    "ticketid": 84
}

Visa ärende

Metod: GETEndpoint: /api/tickets/{ticketId}

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  https://din-hit-domän/api/tickets/1

Exempel på svar:

json

{
    "status": "OK",
    "ticket": {
        "id": 85,
        "submitter_name": "Robin Friberg",
        "submitter_email": "robin@devpeak.se",
        "subject": "An example ticket",
        "date": "2023-07-14T13:42:10.000000Z",
        "closed_date": null,
        "description": "<p>With a somewhat normal description.</p>",
        "priority": "low",
        "duedate": null,
        "last_activity": "2023-07-14T13:42:10.000000Z",
        "link": "https://din-hit-domän/view?id=85"
    }
}

Inventarier via API

Anropen nedan låter andra system läsa och underhålla inventarier. De kräver två saker utöver en giltig API-nyckel:

Modul - Inventarier måste vara påslagen i kön.
Nyckelns användare måste ha behörigheten att hantera inventarier. Den ingår som standard bara i rollerna Admin och Global admin — vill ni låta vanliga handläggare använda anropen behöver ni lägga till resursen på deras roll under Inställningar → Roller.

Att skapa, ändra eller radera inventarier kräver dessutom en nyckel med läs- och skrivrättigheter.

Hämta fältlistan först

Fältvärden anges med fältnamnet, inte med något internt id. Anropet Lista inventarietabeller returnerar varje tabells fält med namn, typ och eventuella valbara värden — börja där.

Så här skickas värden beroende på fälttyp:

Fälttyp	Format
Text	Sträng, högst 255 tecken
Datum	`ÅÅÅÅ-MM-DD`, till exempel `2026-01-15`
Ja/Nej	`true` eller `false`
Lista	Exakt ett av tabellens valbara värden
Relation	Id:t för den inventarie som ska pekas ut

Ett tomt värde ("" eller null) tömmer fältet. Obligatoriska fält går inte att tömma.

Historiken börjar vid första ändringen

När en inventarie skapas skrivs ingen historikpost — precis som i gränssnittet. Historiken börjar först när ett värde ändras.

Fält med standardvärde fylls inte i automatiskt via API:et. Skicka med de värden ni vill ha.

Lista inventarietabeller

Metod: GETEndpoint: /api/queues/{queueId}/assettables

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  https://din-hit-domän/api/queues/1/assettables

Exempel på svar:

json

{
    "status": "OK",
    "assettables_count": 1,
    "assettables": [
        {
            "id": 3,
            "name": "Datorer",
            "display_field": 10,
            "display_template": "{Serienummer} – {Status}",
            "fields": [
                {
                    "id": 10,
                    "name": "Serienummer",
                    "type": "string",
                    "mandatory": true,
                    "unique": true,
                    "position": 0,
                    "default_value": null,
                    "related_asset_table_id": null,
                    "options": null
                },
                {
                    "id": 11,
                    "name": "Inköpsdatum",
                    "type": "date",
                    "mandatory": false,
                    "unique": false,
                    "position": 1,
                    "default_value": "today",
                    "related_asset_table_id": null,
                    "options": null
                },
                {
                    "id": 12,
                    "name": "Status",
                    "type": "enum",
                    "mandatory": false,
                    "unique": false,
                    "position": 2,
                    "default_value": null,
                    "related_asset_table_id": null,
                    "options": ["Aktiv", "Lager"]
                },
                {
                    "id": 13,
                    "name": "Ägare",
                    "type": "related",
                    "mandatory": false,
                    "unique": false,
                    "position": 3,
                    "default_value": null,
                    "related_asset_table_id": 4,
                    "options": null
                }
            ]
        }
    ]
}

Lista inventarier i en tabell

Metod: GETEndpoint: /api/assettables/{assetTableId}/assets

Valfria parametrar:

search — matchar mot inventariernas fältvärden
order — asc eller desc, standard desc
limit — antal per sida, standard 50
page — sidnummer, standard 1

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  'https://din-hit-domän/api/assettables/3/assets?search=ABC&limit=25'

Exempel på svar:

json

{
    "status": "OK",
    "page": 1,
    "limit": 50,
    "assets_count": 128,
    "assets": [
        {
            "id": 501,
            "asset_table_id": 3,
            "display_value": "ABC-123 – Aktiv",
            "fields": {
                "Serienummer": "ABC-123",
                "Inköpsdatum": "2026-01-15",
                "Status": "Aktiv",
                "Ägare": {
                    "id": 42,
                    "display_value": "Anna Andersson"
                }
            }
        }
    ]
}

Ett relationsfält returneras som ett objekt med både id och display_value. Vid skrivning skickas bara id:t.

Visa inventarie

Metod: GETEndpoint: /api/assets/{assetId}

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  https://din-hit-domän/api/assets/501

Exempel på svar:

json

{
    "status": "OK",
    "asset": {
        "id": 501,
        "asset_table_id": 3,
        "display_value": "ABC-123 – Aktiv",
        "fields": {
            "Serienummer": "ABC-123",
            "Utrangerad": false,
            "Ägare": {
                "id": 42,
                "display_value": "Anna Andersson"
            }
        },
        "tickets": [
            {
                "id": 88,
                "subject": "Trasig skärm"
            }
        ]
    }
}

Skapa inventarie

Metod: POSTEndpoint: /api/assettables/{assetTableId}/assets

Krävda parametrar:

fields — ett objekt med fältnamn som nycklar

Samtliga obligatoriska fält i tabellen måste ha ett värde.

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  -H 'Content-Type: application/json' -X POST \
  -d '{"fields":{"Serienummer":"ABC-123","Inköpsdatum":"2026-01-15","Status":"Aktiv","Ägare":42}}' \
  https://din-hit-domän/api/assettables/3/assets

Exempel på svar:

json

{
    "status": "OK",
    "message": "Inventarien har skapats",
    "asset": {
        "id": 501,
        "asset_table_id": 3,
        "display_value": "ABC-123 – Aktiv",
        "fields": {
            "Serienummer": "ABC-123",
            "Inköpsdatum": "2026-01-15",
            "Status": "Aktiv",
            "Ägare": {
                "id": 42,
                "display_value": "Anna Andersson"
            }
        }
    }
}

Om ett värde inte håller måttet svarar API:et med statuskod 422 och ett fel per fält:

json

{
    "message": "The given data was invalid.",
    "errors": {
        "fields.Inköpsdatum": [
            "Fältet måste vara ett datum i formatet ÅÅÅÅ-MM-DD."
        ],
        "fields.Ägare": [
            "Det finns ingen inventarie med det id:t i den refererade tabellen."
        ]
    }
}

Ändra inventarie

Metod: PATCHEndpoint: /api/assets/{assetId}

Krävda parametrar:

fields — ett objekt med fältnamn som nycklar

Bara de fält som skickas med ändras; övriga lämnas orörda. Ett obligatoriskt fält som redan har ett värde behöver alltså inte skickas med, men det går inte att tömma.

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  -H 'Content-Type: application/json' -X PATCH \
  -d '{"fields":{"Status":"Lager"}}' \
  https://din-hit-domän/api/assets/501

Exempel på svar:

json

{
    "status": "OK",
    "asset": {
        "id": 501,
        "asset_table_id": 3,
        "display_value": "ABC-123 – Lager",
        "fields": {
            "Serienummer": "ABC-123",
            "Status": "Lager"
        }
    }
}

Radera inventarie

Metod: DELETEEndpoint: /api/assets/{assetId}

Relationer till den raderade inventarien försvinner

Om andra inventarier pekar ut den som raderas tas deras värde i det relationsfältet bort helt, utan spår i historiken. Kontrollera historiken eller relationerna innan ni raderar.

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  -X DELETE https://din-hit-domän/api/assets/501

Exempel på svar:

json

{
    "status": "OK",
    "message": "Inventarien har raderats"
}

Läs ändringshistorik för en inventarie

Metod: GETEndpoint: /api/assets/{assetId}/history

Historiken innehåller tre sorters poster, som skiljs åt av type:

field — ett fältvärde ändrades
ticket — ett ärende kopplades eller kopplades bort
reference — en annan inventarie började eller slutade peka på den här

Posterna kommer i fallande datumordning. Använd type för att skilja dem åt maskinellt; field_name är översatt och kan ändras.

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  https://din-hit-domän/api/assets/501/history

Exempel på svar:

json

{
    "status": "OK",
    "asset_id": 501,
    "history": [
        {
            "type": "field",
            "field_name": "Status",
            "old_value": "Aktiv",
            "new_value": "Lager",
            "changed_by": "Sarah",
            "changed_at": "2026-08-10T09:12:00.000000Z"
        },
        {
            "type": "ticket",
            "field_name": "Ärende",
            "old_value": null,
            "new_value": "[88] Trasig skärm",
            "ticket_id": 88,
            "changed_by": "Sarah",
            "changed_at": "2026-08-09T14:03:00.000000Z"
        },
        {
            "type": "reference",
            "field_name": "Refereras av (Datorer)",
            "old_value": null,
            "new_value": "SN-999",
            "changed_by": "Sarah",
            "changed_at": "2026-08-08T11:00:00.000000Z"
        }
    ]
}

Koppla inventarie till ärende

Metod: POSTEndpoint: /api/assets/{assetId}/tickets

Krävda parametrar:

ticket_id

Kräver behörighet att ändra ärenden i ärendets kö, utöver behörigheten att hantera inventarier.

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  -H 'Content-Type: application/json' -X POST \
  -d '{"ticket_id":88}' \
  https://din-hit-domän/api/assets/501/tickets

Exempel på svar:

json

{
    "status": "OK",
    "message": "Ärendet har kopplats till inventarien"
}

Koppla bort inventarie från ärende

Metod: DELETEEndpoint: /api/assets/{assetId}/tickets/{ticketId}

Exempel på anrop:

curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  -X DELETE https://din-hit-domän/api/assets/501/tickets/88

Exempel på svar:

json

{
    "status": "OK",
    "message": "Ärendet har kopplats bort från inventarien"
}

REST-API ​

Autentisering ​

Lista tillgängliga köer ​

Lista ärenden i en kö ​

Sök efter ärenden i en kö ​

Skapa nytt ärende ​

Lista ärendemallar ​

Skapa nya ärenden från en ärendemall ​

Visa ärende ​

Inventarier via API ​

Lista inventarietabeller ​

Lista inventarier i en tabell ​

Visa inventarie ​

Skapa inventarie ​

Ändra inventarie ​

Radera inventarie ​

Läs ändringshistorik för en inventarie ​

Koppla inventarie till ärende ​

Koppla bort inventarie från ärende ​

REST-API

Autentisering

Lista tillgängliga köer

Lista ärenden i en kö

Sök efter ärenden i en kö

Skapa nytt ärende

Lista ärendemallar

Skapa nya ärenden från en ärendemall

Visa ärende

Inventarier via API

Lista inventarietabeller

Lista inventarier i en tabell

Visa inventarie

Skapa inventarie

Ändra inventarie

Radera inventarie

Läs ändringshistorik för en inventarie

Koppla inventarie till ärende

Koppla bort inventarie från ärende