Create a certificate

POST/api/v1/workspaces/{slug}/certificates

Create a new certificate in a workspace

Creates a certificate (defaults to draft) and an owned template draft. name is required.

Authorization

Scopecertificates:write

Authorization: Bearer vc_...

Requires certificates:write (or full access) and an active Pro seat. Enabling request or correction forms also requires an active seat for operate features.

Path parameters

slug*string

Workspace slug

Example: acme

Body parameters

name*string

Certificate name

Example: Python Fundamentals

status?string

draft, active, or archived (defaults to draft)

Example: active

description?string

What this certificate represents (max 4000 chars)

Example: Completion of the Python fundamentals track

certificate_type?string

One of certificate, badge, certification, course, workshop, event, membership, recognition

Example: course

level?string

One of beginner, intermediate, advanced, professional

Example: beginner

duration?string

Free-text time to earn (max 80 chars)

Example: 8 weeks

learn_more_url?string

http or https URL

Example: https://example.com/python

earning_criteria?string[]

Up to 10 criteria, each ≤ 500 chars

Example: ["Complete all modules"]

skill_ids?UUID[]

Ordered skill ids to link (max 20)

request_form_enabled?boolean

Enable public request form

Example: true

require_request_form_submission?boolean

Hold imported recipients until they submit the form

Example: true

request_form_mode?string

Defaults to manual_approval

correction_form_enabled?boolean

Enable correction form

Example: true

correction_form_mode?string

Defaults to manual_approval

Attribute definitions, form fields, and validity_days are set via update after create when needed.

Response schema

id*UUID

Certificate id

workspace_id*UUID

Owning workspace id

name*string

Certificate name

status*string

`draft`, `active`, or `archived`

validity_days?integer

Days until issued credentials expire; null if no expiry

request_form_enabled*boolean

Whether the public request form is enabled

require_request_form_submission*boolean

Hold imported recipients until they submit the request form

request_form_mode*string

Request form approval mode (e.g. `manual_approval`)

correction_form_enabled*boolean

Whether the correction form is enabled

correction_form_mode*string

Correction form approval mode

request_form_token?string

Public request-form token when enabled

correction_form_token?string

Public correction-form token when enabled

attributes*object[]

Attribute definitions (`key`, `label`, …)

request_form_fields*object[]

Request form field definitions

correction_form_fields*object[]

Correction form field definitions

description*string

What this certificate represents

certificate_type?string

One of `certificate`, `badge`, `certification`, `course`, `workshop`, `event`, `membership`, `recognition`

level?string

One of `beginner`, `intermediate`, `advanced`, `professional`

duration?string

Free-text time to earn

learn_more_url?string

`http` or `https` URL

earning_criteria*string[]

Criteria listed on the credential

created_at*datetime

Created timestamp (RFC 3339)

updated_at*datetime

Updated timestamp (RFC 3339)

skills*object[]

Linked skills (`id`, `name`); may be empty

has_template*boolean

Whether a template draft or published version exists

published_template_version?integer

Latest published template version number when published

pending_recipient_count*integer

Pending (not yet issued) recipients

active_recipient_count*integer

Active issued recipients