Accredible Skills Frameworks API
A Skills Framework is a structured taxonomy of skills. Accredible maintains external frameworks such as O*NET, ESCO and NACE, and your organization can upload its own custom frameworks. Tagging a Group against a framework replaces the free-text `learning_outcomes` list with skills that carry a stable identifier and a known position in a recognized taxonomy. These endpoints are **read-only**. Uploading frameworks, editing their skills, publishing and retiring versions are all managed in the [Accredible Dashboard](https://dashboard.accredible.com/) — the API lets you discover the frameworks available to you, search their skills, and select those skills on a Group. ## Frameworks are versioned You always tag against a **version**, never a framework. Each framework in the list response carries a `versions` array; take the `id` of the version you want and send it as `skill_framework_version_id` when you create or update a Group. Only published versions (`active` and `retired`) are ever returned. The version's status decides what a write does. Tagging against the `active` version attaches your skills. Tagging against a `retired` version never fails the request — the Group is still created or updated, but the skills are ignored and the response is a `207` with a `version_retired` error. ## Skills know where they live A skill sits at a position in its framework's hierarchy, and in some taxonomies it legitimately sits in more than one. The skills search response returns one row per skill with a `breadcrumbs` array — one trail per placement, each trail listing the skill's ancestors from the root down to its immediate parent. When you attach a skill to a Group you send both the skill `id` and the `breadcrumb_ids` of the trail you mean, so the placement is unambiguous. The ids in a `breadcrumbs` trail are exactly what `breadcrumb_ids` expects — you can copy them straight from a search result into a Group request. Because the pair `(id, breadcrumb_ids)` identifies a placement, the same skill id may appear more than once with different trails. ## Reading skills back off a credential You do not need to call these endpoints to display a credential's skills. [Credential](#tag/Credentials) responses carry a `skills` array for the Group the credential was issued from, with each skill's external `identifier` and its `breadcrumbs` trail, so a consumer pulling credentials can render skills without a second request. The framework those skills belong to is a property of the Group, not of the credential, so it is not repeated on every credential. Follow the credential's `group_id` to [View a Group](#operation/View%20a%20Group) and read `skill_framework` — the Group response carries the same `skills` array alongside it. The array is empty when the Group uses free-text `learning_outcomes`, when it has a framework selected but no skills that can be tagged, and when the credential has no Group at all. ## Relationship to existing Group fields Framework skills and free-text `learning_outcomes` can both be set on a Group; neither is rejected or cleared by the other. Where a credential displays a single skills list, framework skills take precedence. `skill_category_id` is a separate, unrelated classification and is unaffected. ## Skills that cannot be attached return a 207, not a failed write When skills cannot be attached — because the version is retired, the framework is not available to the Department, a skill id is not in the version, or a breadcrumb trail is invalid — the Group write does not fail. The Group is still created or updated, every valid skill is attached, the rest are ignored, and each reason is itemized in the `errors` array of a `207 Multi-Status` response. Attachment is per-skill, so one invalid skill does not stop the others from attaching. Read `skill_framework` and `skills` off a `207` response to see exactly what was saved. There is one exception. If your plan does not include access to skills frameworks and you send framework parameters for a Group that is **already** framework-backed, [Update a Group](#operation/Update%20a%20Group) returns a hard `403` and nothing in the request is saved, including changes to unrelated fields. The Group's framework and skills stay saved and readable, and moving it to free-text skills with `"framework_skills": null` is still allowed. See [Skills Frameworks Error Handling](#section/Errors/Skills-Frameworks-Error-Handling) for the full list of codes.
GET
/v1/skill_frameworks
View all Skill Frameworks
#
GET
/v1/skill_frameworks/{skill_framework_id}/versions/{version_id}/skills
Search Skills in a Framework Version
#
Documentation
Specifications
Other Resources
Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Accredible Credential Skills Frameworks API
version: 25.08.0
description: 'The Accredible Credential API allows you to create and interact with badges and certificates called Accredible Credentials. There are 3 main objects in Accredible: Credentials, Groups and Designs. ### Getting Started with the API - Video Walkthrough
# Objects Overview
## Credentials
Credentials are the core object in the API. They collect all of the data related to a course, training activity or achievement and the recipient/participant information. You should create a credential for each achievement completion that a recipient has. For example if John Doe finishes the Programming 101 course we should create one credential to represent that. If John Doe achieves something else then he would need a new credential. ## Groups
Groups represent an achievement such as a course or qualification. They contain information about the achievement and have multiple Credentials attached to them. For example you should create a group for the Introduction to Programming course. You''d provide the Course Name, Course Description and Course URL. In the future you can pass the name or ID of this group when creating a credential so that the credential is passed all the information relating to the achievement. ## Designs
Designs provide a visual specification for how a Credential should be rendered. Designs can be used across multiple Groups. For example if we have three courses: Intro to Basic Programming, Intro to Advanced Programming and Intro to DevOps each of these may have the same design for their Credentials. When creating or updating their corresponding Groups you would attach the desired design accordingly. ## Departments
Departments, if enabled for your account allow you to manage multiple, independent organization groups. Each Department is entirely separate with its own Designs, Groups, Branding, etc. You cannot share data between Departments except Billing and Administrators. ## Attributes
Attributes, are used to merge information with your badge or certificate designs and email templates. Attributes act as placeholders for information and can be added to certificate designs and email templates. ## Skills Frameworks
Skills Frameworks are structured taxonomies of skills — Accredible-maintained ones such as O*NET, ESCO and NACE, plus any your organization uploads itself. Tagging a Group against a framework version replaces the Group''s free-text `learning_outcomes` with skills that carry a stable identifier and a known position in a recognized taxonomy. For example, instead of listing `"Reading Books"` on your Introduction to Programming group, you can attach the O*NET skill `Reading Comprehension` together with the trail it sits on — Worker Requirements → Basic Skills → Content. Frameworks are read-only over the API: you discover the frameworks enabled for a department, search their skills, then select those skills when creating or updating a Group. Uploading and managing frameworks is done in the Accredible Dashboard. # API Keys
API keys are used as Authorization tokens in the header in all authenticated API endpoints. These Keys are managed in the Accredible Dashboard. There are two types of API Keys, those that are account wide and work on all assets and those that are related to a specific department. API keys scoped to a specific department can only access the resources (Credentials, Groups, Designs etc.) belonging to that department. # Single sign-on options
Single sign-on in addition to the student authentication provided by Accredible, you can also use single sign-on to authenticate your student into Accredible and they can directly sign-in. SSO is also available via our Integrations and via SAML 2.0. # Rate Limiting
We allow up to 2000 requests every 5 minutes from a single IP address, but some higher security endpoints have stricter rate limiting. Requests are counted in 30 second periods.'
servers:
- url: https://api.accredible.com/
description: Production environment - US
- url: https://eu.api.accredible.com/
description: Production environment - EU
- url: https://sandbox.api.accredible.com/
description: Sandbox environment - Testing environment
tags:
- name: Skills Frameworks
description: 'A Skills Framework is a structured taxonomy of skills. Accredible maintains external frameworks such as O*NET, ESCO and NACE, and your organization can upload its own custom frameworks. Tagging a Group against a framework replaces the free-text `learning_outcomes` list with skills that carry a stable identifier and a known position in a recognized taxonomy. These endpoints are **read-only**. Uploading frameworks, editing their skills, publishing and retiring versions are all managed in the Accredible Dashboard — the API lets you discover the frameworks available to you, search their skills, and select those skills on a Group. ## Frameworks are versioned
You always tag against a **version**, never a framework. Each framework in the list response carries a `versions` array; take the `id` of the version you want and send it as `skill_framework_version_id` when you create or update a Group. Only published versions (`active` and `retired`) are ever returned. The version''s status decides what a write does. Tagging against the `active` version attaches your skills. Tagging against a `retired` version never fails the request — the Group is still created or updated, but the skills are ignored and the response is a `207` with a `version_retired` error. ## Skills know where they live
A skill sits at a position in its framework''s hierarchy, and in some taxonomies it legitimately sits in more than one. The skills search response returns one row per skill with a `breadcrumbs` array — one trail per placement, each trail listing the skill''s ancestors from the root down to its immediate parent. When you attach a skill to a Group you send both the skill `id` and the `breadcrumb_ids` of the trail you mean, so the placement is unambiguous. The ids in a `breadcrumbs` trail are exactly what `breadcrumb_ids` expects — you can copy them straight from a search result into a Group request. Because the pair `(id, breadcrumb_ids)` identifies a placement, the same skill id may appear more than once with different trails. ## Reading skills back off a credential
You do not need to call these endpoints to display a credential''s skills. Credential responses carry a `skills` array for the Group the credential was issued from, with each skill''s external `identifier` and its `breadcrumbs` trail, so a consumer pulling credentials can render skills without a second request. The framework those skills belong to is a property of the Group, not of the credential, so it is not repeated on every credential. Follow the credential''s `group_id` to View a Group and read `skill_framework` — the Group response carries the same `skills` array alongside it. The array is empty when the Group uses free-text `learning_outcomes`, when it has a framework selected but no skills that can be tagged, and when the credential has no Group at all. ## Relationship to existing Group fields
Framework skills and free-text `learning_outcomes` can both be set on a Group; neither is rejected or cleared by the other. Where a credential displays a single skills list, framework skills take precedence. `skill_category_id` is a separate, unrelated classification and is unaffected. ## Skills that cannot be attached return a 207, not a failed write
When skills cannot be attached — because the version is retired, the framework is not available to the Department, a skill id is not in the version, or a breadcrumb trail is invalid — the Group write does not fail. The Group is still created or updated, every valid skill is attached, the rest are ignored, and each reason is itemized in the `errors` array of a `207 Multi-Status` response. Attachment is per-skill, so one invalid skill does not stop the others from attaching. Read `skill_framework` and `skills` off a `207` response to see exactly what was saved. There is one exception.'
paths:
/v1/skill_frameworks:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
skill_frameworks:
type: array
items:
type: object
properties:
id:
type: number
description: Unique identifier of the Skill Framework.
name:
type: string
description: Display name of the framework, for example `O*NET Skills`.
source_type:
type: string
description: '`external` for a framework maintained by Accredible, `custom` for one uploaded by your organization.'
enum:
- external
- custom
taxonomy:
type:
- string
- 'null'
description: 'The published taxonomy an external framework comes from: `ONET`, `ESCO` or `NACE`. Always `null` for custom frameworks.'
status:
type: string
description: Always `enabled` — only frameworks enabled for the requested Department are returned. Version retirement is reported per version inside `versions`, not here.
enum:
- enabled
provider:
type:
- string
- 'null'
description: The organization that publishes the framework, for example `U.S. Department of Labor`.
description:
type:
- string
- 'null'
skill_count:
type:
- number
- 'null'
description: Number of skills in the framework's latest active version.
updated_at:
type: string
attribution:
type: object
description: Attribution that the framework's licence requires you to display wherever you show its skills.
properties:
text:
type:
- string
- 'null'
url:
type:
- string
- 'null'
versions:
type: array
description: Published versions of the framework, oldest first. Only `active` and `retired` versions are returned — versions still being prepared are never exposed. Use a version's `id` as the `skill_framework_version_id` when creating or updating a Group.
items:
type: object
properties:
id:
type: number
description: Pass this value as `skill_framework_version_id` on a Group.
version:
type: string
description: The publisher's version label, for example `30.0`.
skill_count:
type: number
status:
type: string
description: Skills can only be attached to a Group from an `active` version. Attempting to use a `retired` version returns a `207` with a `version_retired` error.
enum:
- active
- retired
valid_from:
type:
- string
- 'null'
format: date
valid_to:
type:
- string
- 'null'
format: date
description: The date this version stops being usable. `null` for a version with no end date.
required:
- id
- version
- skill_count
- status
- valid_from
- valid_to
required:
- id
- name
- source_type
- taxonomy
- status
- provider
- description
- skill_count
- updated_at
- attribution
- versions
meta:
type: object
properties:
current_page:
type: number
next_page:
type:
- number
- 'null'
prev_page:
type:
- number
- 'null'
total_pages:
type: number
total_count:
type: number
page_size:
type: number
example:
skill_frameworks:
- id: 44
name: O*NET Skills
source_type: external
taxonomy: ONET
status: enabled
provider: U.S. Department of Labor
description: null
skill_count: 350
updated_at: '2026-06-10T03:12:26.427Z'
attribution:
text: O*NET is sponsored by the U.S. Department of Labor
url: https://www.onetonline.org/
versions:
- id: 511
version: '29.0'
skill_count: 347
status: retired
valid_from: '2026-01-01'
valid_to: '2026-04-08'
- id: 512
version: '30.0'
skill_count: 350
status: active
valid_from: '2026-04-08'
valid_to: null
- id: 177
name: Internal Competency Model
source_type: custom
taxonomy: null
status: enabled
provider: null
description: Skills maintained by our Learning and Development team
skill_count: 9
updated_at: '2026-06-22T09:15:04.881Z'
attribution:
text: null
url: null
versions:
- id: 239
version: '1.0'
skill_count: 9
status: active
valid_from: '2026-06-22'
valid_to: null
meta:
current_page: 1
next_page: null
prev_page: null
total_pages: 1
total_count: 2
page_size: 5
'400':
description: Bad Request - `missing_department_id` when the required `department_id` parameter is not supplied.
headers: {}
content:
application/json:
schema:
type: object
properties:
code:
type: number
message:
type: string
status:
type: string
errors:
type: object
example:
code: 400
message: department_id is required
status: missing_department_id
errors: {}
'403':
description: Forbidden - `plan_not_entitled` when your plan does not include skills frameworks, or `invalid_department` when the given `department_id` is not a Department your API key can access.
headers: {}
content:
application/json:
schema:
type: object
properties:
code:
type: number
message:
type: string
status:
type: string
errors:
type: object
example:
code: 403
message: Your plan does not include access to skills frameworks
status: plan_not_entitled
errors: {}
summary: View all Skill Frameworks
operationId: ViewAllSkillFrameworks
description: 'Lists the Skill Frameworks enabled for a Department, each with its published versions.
This is the starting point for tagging a Group with framework skills. Pick a framework, take the `id` of the version you want from its `versions` array, then use that value as `skill_framework_version_id` when you create or update a Group.
Only frameworks enabled for the requested Department are returned, so the response is exactly the set you are allowed to attach to Groups in that Department. Frameworks that an administrator has added but not yet enabled are not listed.
When Accredible retires an external framework for your Department, it stays listed throughout the notice period so your integration is not broken by an abrupt removal. Its version is reported with `status` `retired` and a `valid_to` date telling you when it stops working.'
tags:
- Skills Frameworks
parameters:
- name: department_id
in: query
description: The Department to list frameworks for. Required, including for API keys scoped to a single Department. Must be a Department your API key can access, otherwise a `403 Forbidden` is returned.
required: true
schema:
type: integer
- name: page
in: query
description: The pagination page. Defaults to 1.
schema:
type: integer
- name: page_size
in: query
description: The pagination response size. Defaults to 5, maximum 10. Values above the maximum are capped, and values that are not a positive number fall back to the default. The size actually applied is returned as `meta.page_size`.
schema:
type: integer
security:
- ApiKeyAuth: []
x-code-samples:
- lang: cURL
label: cURL
source: "curl -X GET \\\n \"https://api.accredible.com/v1/skill_frameworks?department_id=12345\" \\\n -H \"Authorization: Token token=YOUR_API_KEY\""
x-operation-id-source: normalized
x-operation-id-original: View all Skill Frameworks
/v1/skill_frameworks/{skill_framework_id}/versions/{version_id}/skills:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
skills:
type: array
items:
type: object
properties:
id:
type: number
description: Unique identifier of the skill. Pass this as `framework_skills[].id` when attaching the skill to a Group.
name:
type: string
description: Display name of the skill.
identifier:
type:
- string
- 'null'
description: The publisher's own identifier for the skill, for example an O*NET element id or an ESCO URI. `null` when the framework does not provide one.
description:
type:
- string
- 'null'
breadcrumbs:
type: array
description: 'Every place this skill sits in the framework''s hierarchy. Each entry is one trail, listing the skill''s ancestors from the root down to its immediate parent — the skill itself is not repeated in its own trail.
Most skills have a single trail. Some taxonomies legitimately place one skill in more than one branch, in which case there is one trail per placement. A skill that sits at the root of the framework has no ancestors and returns `[]`.
The `id` values of a trail are exactly what `framework_skills[].breadcrumb_ids` expects when you attach the skill to a Group, in the same order.'
items:
type: array
items:
type: object
properties:
id:
type: number
name:
type: string
required:
- id
- name
required:
- id
- name
- identifier
- description
- breadcrumbs
meta:
type: object
properties:
current_page:
type: number
next_page:
type:
- number
- 'null'
prev_page:
type:
- number
- 'null'
total_pages:
type: number
total_count:
type: number
page_size:
type: number
example:
skills:
- id: 44923
name: Absorb (Learning Management Systems)
identifier: http://data.europa.eu/esco/skill/0189f448-4f52-4fcb-a05f-a4b0e6b0ba1d
description: null
breadcrumbs:
- - id: 44696
name: Knowledge
- id: 44697
name: Information And Communication Technologies (Icts)
- id: 44862
name: Database And Network Design And Administration
- - id: 44696
name: Knowledge
- id: 44764
name: Business, Administration And Law
- id: 44766
name: Management And Administration
- id: 44924
name: Learning Management Systems
- id: 44931
name: Manage Learning Content
identifier: http://data.europa.eu/esco/skill/6a1ec1f2-6b0d-4f1e-9c2f-8d5b1c7a4e30
description: Create, curate and maintain the material used in a training programme.
breadcrumbs:
- - id: 44700
name: Skills
- id: 44812
name: Management Skills
meta:
current_page: 1
next_page: 2
prev_page: null
total_pages: 347
total_count: 694
page_size: 2
'400':
description: Bad Request - `invalid_query` when `query` is missing or shorter than 2 characters, or `invalid_version` when the version does not belong to the framework or is not published.
headers: {}
content:
application/json:
schema:
type: object
properties:
code:
type: number
message:
type: string
status:
type: string
errors:
type: object
example:
code: 400
message: Query must be at least 2 characters
status: invalid_query
errors: {}
'403':
description: Forbidden - `plan_not_entitled` when your plan does not include skills frameworks.
headers: {}
content:
application/json:
schema:
type: object
properties:
code:
type: number
message:
type: string
status:
type: string
errors:
type: object
example:
code: 403
message: Your plan does not include access to skills frameworks
status: plan_not_entitled
errors: {}
'404':
description: Not Found - the framework does not exist, or it is a custom framework belonging to another organization.
headers: {}
content:
application/json:
schema:
type: object
properties:
code:
type: number
message:
type: string
status:
type: string
errors:
type: object
example:
code: 404
message: Skills framework not found
status: not_found
errors: {}
summary: Search Skills in a Framework Version
operationId: SearchSkillsInAFrameworkVersion
description: 'Searches the skills inside a specific version of a Skill Framework.
The `query` is matched against both the skill name and the publisher''s `identifier`, so you can look a skill up either way. Use this endpoint to resolve the skill `id` values and `breadcrumb_ids` trails you then send as `framework_skills` when creating or updating a Group.
The version is always explicit. Take the version `id` from the `versions` array returned by View all Skill Frameworks — there is no "latest version" shortcut, which means a skill id you look up here is guaranteed to still be valid for the version you attach it to.
Each skill appears **once**, with all of its positions in the hierarchy collected under `breadcrumbs`. A skill placed in two branches of the taxonomy is one row with two trails, not two rows.
Search is intentionally broader than what you can attach: any framework your API key can see is searchable, including one that is not enabled for a particular Department. Whether a skill can actually be attached is checked when you write to a Group.'
tags:
- Skills Frameworks
parameters:
- name: skill_framework_id
in: path
description: ID of the Skill Framework to search within, as returned by the framework list endpoint.
required: true
schema:
type: integer
- name: version_id
in: path
description: ID of the framework version to search within, taken from the framework's `versions` array. Must belong to the given framework and be a published (`active` or `retired`) version.
required: true
schema:
type: integer
- name: query
in: query
description: Text to search for, matched as a partial, case-insensitive match against the skill name and the publisher's `identifier`. Required, and must be at least 2 characters.
required: true
schema:
type: string
- name: page
in: query
description: The pagination page. Defaults to 1.
schema:
type: integer
- name: page_size
in: query
description: The pagination response size. Defaults to 50, which is also the maximum. Values above the maximum are capped, and values that are not a positive number fall back to the default.
schema:
type: integer
security:
- ApiKeyAuth: []
x-code-samples:
- lang: cURL
label: cURL
source: "curl -X GET \\\n \"https://api.accredible.com/v1/skill_frameworks/44/versions/512/skills?query=reading\" \\\n -H \"Authorization: Token token=YOUR_API_KEY\""
x-operation-id-source: normalized
x-operation-id-original: Search Skills in a Framework Version
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: 'Use the format: Token token=YOUR_API_KEY'
x-provenance:
method: harvested
publisher: Accredible
source: https://docs.api.accredible.com/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)