API docs by Redocly

Catwise Takenbieb Partner API (1.0.0)

Download OpenAPI specification:

Universeel koppelvlak waarmee externe partners taken aanleveren aan de openbare Takenbieb van Catwise.

Globale werking

  1. Catwise stelt de koppeling in en verstrekt de partner OAuth2-credentials (client_id + client_secret).
  2. De partner wisselt die via POST /oauth/token in voor een access token en kan daarna taken aanmaken, bijwerken, verwijderen en opvragen.
  3. Wijzigingen worden niet direct doorgevoerd. Elke mutatie (create/update/delete) komt eerst als verzoek in Catwise te staan en moet door een medewerker van Catwise worden geaccordeerd of afgekeurd.
  4. De partner ziet de stand van zaken via het read-only veld review_status (pending / approved / rejected) op elke taak.

Identifiers

  • id — door Catwise toegekend, stabiel, gebruikt in alle URL-paden.
  • external_id — de eigen referentie van de partner. Uniek per partner en onveranderlijk na aanmaken; een tweede POST /task met een bestaande external_id levert 409.

Rate limiting

Verzoeken worden per partner gelimiteerd. Boven de limiet antwoordt de API met 429 Too Many Requests; implementeer een backoff en probeer het daarna opnieuw.

Authenticatie

OAuth 2.0 token-uitgifte.

Access token opvragen

Wisselt de client_id en client_secret (verstrekt door Catwise) in voor een access token via de OAuth 2.0 Client Credentials grant. Gebruik het teruggegeven token als Authorization: Bearer <access_token> bij alle overige endpoints. De client-credentials mogen ook als HTTP Basic-header worden meegestuurd in plaats van in de body.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string

Moet client_credentials zijn.

client_id
string or null

Door Catwise verstrekte client-id. Mag ook via HTTP Basic worden meegestuurd.

client_secret
string or null

Door Catwise verstrekte client-secret. Mag ook via HTTP Basic worden meegestuurd.

scope
string or null

Optioneel; spatie-gescheiden lijst van gevraagde scopes.

Responses

Response Schema: application/json
access_token
required
string
token_type
required
string
Value: "Bearer"
expires_in
required
integer
Value: 3600
scope
required
string

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "string"
}

Tasks

Beheer van eigen taken in de Takenbieb.

Taak aanmaken

Levert een nieuwe taak aan. Dit creëert intern een New Item Request. De respons bevat de aangemaakte taak met review_status: pending. De taak verschijnt pas in de openbare Takenbieb nadat Catwise het verzoek accordeert. Een tweede taak met een al bestaande external_id levert 409.

Authorizations:
oauth2
Request Body schema: application/json
required
external_id
required
string <= 255 characters

Eigen referentie van de partner. Uniek per partner.

status
required
string (PartnerTaskStatus)
Enum: "concept" "active" "inactive"

Status van de taak bij de partner (concept / active / inactive).

access
required
string (PartnerTaskAccess)
Enum: "public" "private"

Toegang tot de taak (public / private).

title
required
string <= 255 characters

Titel van de taak, zichtbaar voor de leerling.

source_updated_at
string or null <date-time>

Tijdstip waarop de taak in het bronsysteem van de partner voor het laatst is bijgewerkt.

template_name
string or null <= 255 characters

Naam van de template van de taak in de bieb.

teacher_instructions
string or null

Instructie voor de docent (rich text / HTML toegestaan).

description
string or null

Omschrijving van de taak, zichtbaar voor de leerling.

banner_image_id
integer or null

Id van een eerder via POST /attachments geüploade bijlage die als banner-image dient.

attachment_ids
Array of integers or null

Id's van eerder via POST /attachments geüploade bijlagen die aan deze taak gekoppeld worden.

subjects
Array of strings or null[ items <= 255 characters ]

Vakken (inclusief 'Vakoverstijgend').

education_levels
Array of strings or null[ items <= 255 characters ]

Jaarlagen / niveaus.

tag_ids
Array of integers or null

Id's van tags / thema's (relatie public_portfolio_tags). Op te vragen bij Catwise.

skill_ids
Array of integers or null

Id's van vaardigheden (relatie public_portfolio_skills). Op te vragen bij Catwise.

Array of objects or null

Subvragen die de leerling bij de taak beantwoordt.

Array
question
required
string [ 5 .. 500 ] characters

De vraagtekst van de subvraag.

type
required
string (PartnerTaskQuestionType)
Enum: "single_line" "multi_line" "radio" "star_rating"

Type van de subvraag: single_line, multi_line, radio of star_rating.

required
required
boolean

Of de leerling de subvraag verplicht moet beantwoorden.

order
integer or null >= 0

Volgorde van de subvraag binnen de taak (0-gebaseerd).

options
required
Array of strings [ 2 .. 12 ] items

Keuze-opties; alleen en verplicht bij type radio (2 t/m 12).

Responses

Response Schema: application/json
id
required
integer
external_id
required
string
status
required
string (PartnerTaskStatus)
Enum: "concept" "active" "inactive"
access
required
string (PartnerTaskAccess)
Enum: "public" "private"
title
required
string
source_updated_at
required
string or null (NullableString)
template_name
required
string or null (NullableString)
teacher_instructions
required
string or null (NullableString)
description
required
string or null (NullableString)
banner_image_id
required
integer or null (NullableInteger)
subjects
required
Array of strings
education_levels
required
Array of strings
tag_ids
required
Array of integers
skill_ids
required
Array of integers
attachment_ids
required
Array of integers
review_status
required
string (ReviewStatus)
Enum: "pending" "approved" "rejected"
updated_at
required
string or null <date-time>
required
object or null
id
required
integer
url
required
string
name
required
string
required
Array of objects
Array
id
required
integer
name
required
string
required
Array of objects
Array
id
required
integer
name
required
string
description
required
string or null (NullableString)
required
Array of objects
Array
id
required
integer
url
required
string
name
required
string
required
Array of objects
Array
question
required
string
type
required
string
options
required
Array of strings or null
required
required
boolean
order
required
integer

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "status": "concept",
  • "access": "public",
  • "title": "string",
  • "source_updated_at": "2019-08-24T14:15:22Z",
  • "template_name": "string",
  • "teacher_instructions": "string",
  • "description": "string",
  • "banner_image_id": 0,
  • "attachment_ids": [
    • 0
    ],
  • "subjects": [
    • "string"
    ],
  • "education_levels": [
    • "string"
    ],
  • "tag_ids": [
    • 0
    ],
  • "skill_ids": [
    • 0
    ],
  • "questions": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "external_id": "string",
  • "status": "concept",
  • "access": "public",
  • "title": "string",
  • "source_updated_at": "string",
  • "template_name": "string",
  • "teacher_instructions": "string",
  • "description": "string",
  • "banner_image_id": 0,
  • "subjects": [
    • "string"
    ],
  • "education_levels": [
    • "string"
    ],
  • "tag_ids": [
    • 0
    ],
  • "skill_ids": [
    • 0
    ],
  • "attachment_ids": [
    • 0
    ],
  • "review_status": "pending",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "banner_image": {
    • "id": 0,
    • "url": "string",
    • "name": "string"
    },
  • "tags": [
    • {
      }
    ],
  • "skills": [
    • {
      }
    ],
  • "attachments": [
    • {
      }
    ],
  • "questions": [
    • {
      }
    ]
}

Eén taak opvragen

Geeft één eigen taak van de partner terug, inclusief de read-only velden en de opgeloste tags, skills, bijlagen en banner-image.

Authorizations:
oauth2
path Parameters
task
required
integer

Responses

Response Schema: application/json
id
required
integer
external_id
required
string
status
required
string (PartnerTaskStatus)
Enum: "concept" "active" "inactive"
access
required
string (PartnerTaskAccess)
Enum: "public" "private"
title
required
string
source_updated_at
required
string or null (NullableString)
template_name
required
string or null (NullableString)
teacher_instructions
required
string or null (NullableString)
description
required
string or null (NullableString)
banner_image_id
required
integer or null (NullableInteger)
subjects
required
Array of strings
education_levels
required
Array of strings
tag_ids
required
Array of integers
skill_ids
required
Array of integers
attachment_ids
required
Array of integers
review_status
required
string (ReviewStatus)
Enum: "pending" "approved" "rejected"
updated_at
required
string or null <date-time>
required
object or null
id
required
integer
url
required
string
name
required
string
required
Array of objects
Array
id
required
integer
name
required
string
required
Array of objects
Array
id
required
integer
name
required
string
description
required
string or null (NullableString)
required
Array of objects
Array
id
required
integer
url
required
string
name
required
string
required
Array of objects
Array
question
required
string
type
required
string
options
required
Array of strings or null
required
required
boolean
order
required
integer

Response samples

Content type
application/json
{
  • "id": 0,
  • "external_id": "string",
  • "status": "concept",
  • "access": "public",
  • "title": "string",
  • "source_updated_at": "string",
  • "template_name": "string",
  • "teacher_instructions": "string",
  • "description": "string",
  • "banner_image_id": 0,
  • "subjects": [
    • "string"
    ],
  • "education_levels": [
    • "string"
    ],
  • "tag_ids": [
    • 0
    ],
  • "skill_ids": [
    • 0
    ],
  • "attachment_ids": [
    • 0
    ],
  • "review_status": "pending",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "banner_image": {
    • "id": 0,
    • "url": "string",
    • "name": "string"
    },
  • "tags": [
    • {
      }
    ],
  • "skills": [
    • {
      }
    ],
  • "attachments": [
    • {
      }
    ],
  • "questions": [
    • {
      }
    ]
}

Taak bijwerken

Stuur de volledige gewenste representatie van de taak. Catwise vergelijkt deze met de huidige taak en maakt een Change Request aan met per gewijzigd veld de oude en nieuwe waarde. De wijziging wordt pas doorgevoerd na akkoord; tot die tijd toont de taak review_status: pending. De external_id is onveranderlijk: een afwijkende waarde levert 422.

Authorizations:
oauth2
path Parameters
task
required
integer
Request Body schema: application/json
required
external_id
required
string <= 255 characters

Eigen referentie van de partner. Onveranderlijk na aanmaken.

status
required
string (PartnerTaskStatus)
Enum: "concept" "active" "inactive"

Status van de taak bij de partner (concept / active / inactive).

access
required
string (PartnerTaskAccess)
Enum: "public" "private"

Toegang tot de taak (public / private).

title
required
string <= 255 characters

Titel van de taak, zichtbaar voor de leerling.

source_updated_at
string or null <date-time>

Tijdstip waarop de taak in het bronsysteem van de partner voor het laatst is bijgewerkt.

template_name
string or null <= 255 characters

Naam van de template van de taak in de bieb.

teacher_instructions
string or null

Instructie voor de docent (rich text / HTML toegestaan).

description
string or null

Omschrijving van de taak, zichtbaar voor de leerling.

banner_image_id
integer or null

Id van een eerder via POST /attachments geüploade bijlage die als banner-image dient.

attachment_ids
Array of integers or null

Id's van eerder via POST /attachments geüploade bijlagen die aan deze taak gekoppeld worden.

subjects
Array of strings or null[ items <= 255 characters ]

Vakken (inclusief 'Vakoverstijgend').

education_levels
Array of strings or null[ items <= 255 characters ]

Jaarlagen / niveaus.

tag_ids
Array of integers or null

Id's van tags / thema's (relatie public_portfolio_tags). Op te vragen bij Catwise.

skill_ids
Array of integers or null

Id's van vaardigheden (relatie public_portfolio_skills). Op te vragen bij Catwise.

Array of objects or null

Subvragen die de leerling bij de taak beantwoordt.

Array
question
required
string [ 5 .. 500 ] characters

De vraagtekst van de subvraag.

type
required
string (PartnerTaskQuestionType)
Enum: "single_line" "multi_line" "radio" "star_rating"

Type van de subvraag: single_line, multi_line, radio of star_rating.

required
required
boolean

Of de leerling de subvraag verplicht moet beantwoorden.

order
integer or null >= 0

Volgorde van de subvraag binnen de taak (0-gebaseerd).

options
required
Array of strings [ 2 .. 12 ] items

Keuze-opties; alleen en verplicht bij type radio (2 t/m 12).

Responses

Response Schema: application/json
id
required
integer
external_id
required
string
status
required
string (PartnerTaskStatus)
Enum: "concept" "active" "inactive"
access
required
string (PartnerTaskAccess)
Enum: "public" "private"
title
required
string
source_updated_at
required
string or null (NullableString)
template_name
required
string or null (NullableString)
teacher_instructions
required
string or null (NullableString)
description
required
string or null (NullableString)
banner_image_id
required
integer or null (NullableInteger)
subjects
required
Array of strings
education_levels
required
Array of strings
tag_ids
required
Array of integers
skill_ids
required
Array of integers
attachment_ids
required
Array of integers
review_status
required
string (ReviewStatus)
Enum: "pending" "approved" "rejected"
updated_at
required
string or null <date-time>
required
object or null
id
required
integer
url
required
string
name
required
string
required
Array of objects
Array
id
required
integer
name
required
string
required
Array of objects
Array
id
required
integer
name
required
string
description
required
string or null (NullableString)
required
Array of objects
Array
id
required
integer
url
required
string
name
required
string
required
Array of objects
Array
question
required
string
type
required
string
options
required
Array of strings or null
required
required
boolean
order
required
integer

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "status": "concept",
  • "access": "public",
  • "title": "string",
  • "source_updated_at": "2019-08-24T14:15:22Z",
  • "template_name": "string",
  • "teacher_instructions": "string",
  • "description": "string",
  • "banner_image_id": 0,
  • "attachment_ids": [
    • 0
    ],
  • "subjects": [
    • "string"
    ],
  • "education_levels": [
    • "string"
    ],
  • "tag_ids": [
    • 0
    ],
  • "skill_ids": [
    • 0
    ],
  • "questions": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "external_id": "string",
  • "status": "concept",
  • "access": "public",
  • "title": "string",
  • "source_updated_at": "string",
  • "template_name": "string",
  • "teacher_instructions": "string",
  • "description": "string",
  • "banner_image_id": 0,
  • "subjects": [
    • "string"
    ],
  • "education_levels": [
    • "string"
    ],
  • "tag_ids": [
    • 0
    ],
  • "skill_ids": [
    • 0
    ],
  • "attachment_ids": [
    • 0
    ],
  • "review_status": "pending",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "banner_image": {
    • "id": 0,
    • "url": "string",
    • "name": "string"
    },
  • "tags": [
    • {
      }
    ],
  • "skills": [
    • {
      }
    ],
  • "attachments": [
    • {
      }
    ],
  • "questions": [
    • {
      }
    ]
}

Taak verwijderen

Maakt een Delete Request aan. De taak blijft bestaan met review_status: pending totdat Catwise het verzoek accordeert; daarna is de taak definitief verwijderd (GET geeft 404) en is de external_id weer vrij voor een nieuwe taak.

Authorizations:
oauth2
path Parameters
task
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "external_id": "string",
  • "status": "concept",
  • "access": "public",
  • "title": "string",
  • "source_updated_at": "string",
  • "template_name": "string",
  • "teacher_instructions": "string",
  • "description": "string",
  • "banner_image_id": 0,
  • "subjects": [
    • "string"
    ],
  • "education_levels": [
    • "string"
    ],
  • "tag_ids": [
    • 0
    ],
  • "skill_ids": [
    • 0
    ],
  • "attachment_ids": [
    • 0
    ],
  • "review_status": "pending",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "banner_image": {
    • "id": 0,
    • "url": "string",
    • "name": "string"
    },
  • "tags": [
    • {
      }
    ],
  • "skills": [
    • {
      }
    ],
  • "attachments": [
    • {
      }
    ],
  • "questions": [
    • {
      }
    ]
}

Lijst van eigen taken

Geeft alle taken die door deze partner zijn aangeleverd, gepagineerd als { data, meta }.

Authorizations:
oauth2
query Parameters
status
string

Filter op de status van de taak (concept / active / inactive).

review_status
string

Filter op de beoordelingsstatus binnen Catwise (pending / approved / rejected).

page
integer
Default: 1

Paginanummer (1-gebaseerd).

per_page
integer
Default: 25

Aantal taken per pagina (max 100).

Responses

Response Schema: application/json
required
Array of objects (PartnerTaskResource)
Array
id
required
integer
external_id
required
string
status
required
string (PartnerTaskStatus)
Enum: "concept" "active" "inactive"
access
required
string (PartnerTaskAccess)
Enum: "public" "private"
title
required
string
source_updated_at
required
string or null (NullableString)
template_name
required
string or null (NullableString)
teacher_instructions
required
string or null (NullableString)
description
required
string or null (NullableString)
banner_image_id
required
integer or null (NullableInteger)
subjects
required
Array of strings
education_levels
required
Array of strings
tag_ids
required
Array of integers
skill_ids
required
Array of integers
attachment_ids
required
Array of integers
review_status
required
string (ReviewStatus)
Enum: "pending" "approved" "rejected"
updated_at
required
string or null <date-time>
required
object or null
required
Array of objects
required
Array of objects
required
Array of objects
required
Array of objects
required
object
current_page
required
integer
last_page
required
integer
per_page
required
integer
total
required
integer

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "meta": {
    • "current_page": 0,
    • "last_page": 0,
    • "per_page": 0,
    • "total": 0
    }
}

Bijlagen

Upload en download van bijlagen bij een taak.

Bijlage uploaden

Uploadt een bestand naar Catwise. De respons bevat een Attachment met een door Catwise toegekend id en een Catwise-gehoste url. Het uploaden zelf hoeft niet te worden geaccordeerd; de bijlage wordt pas onderdeel van een taak zodra het id in attachment_ids van een taak wordt opgenomen én de bijbehorende New Item / Change Request is geaccordeerd. Een niet-gekoppelde bijlage kan door Catwise worden opgeruimd.

Authorizations:
oauth2
Request Body schema: multipart/form-data
required
file
required
string <binary> <application/octet-stream>

Het te uploaden bestand.

name
string or null <= 255 characters

Optionele weergavenaam; standaard de bestandsnaam.

Responses

Response Schema: application/json
id
required
integer
url
required
string
name
required
string

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "string",
  • "name": "string"
}

Bijlage downloaden

Downloadt een eerder geüploade bijlage als bestandsstroom. Dit is het endpoint achter het url-veld van een Attachment. Een partner kan alleen zijn eigen bijlagen ophalen.

Authorizations:
oauth2
path Parameters
attachment
required
integer

Responses

Response Schema: application/octet-stream
string <binary>

Response samples

Content type
application/json
{
  • "message": "string"
}