Management API

The Management API provides CRUD operations for platform resources including projects, categories, groups, artifact types, and organizations. Use these endpoints to programmatically manage your Revelry Ai workspace.

Authentication

All requests require an API key. Organization endpoints require a super admin API key.

Authorization: Bearer YOUR_API_KEY

See Managing API Keys for setup instructions.

Base URL

https://app.revelry.ai/api/v1

---

Projects

Manage projects within your organization.

List Projects

Endpoint: GET /api/v1/projects

curl https://app.revelry.ai/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Project

Endpoint: POST /api/v1/projects

Required fields:

• name (string) — Project name
• group_ids (array of integers) — At least one group ID, or use_default_group: true to use the organization's default group

Optional fields:

• overview (string) — Project description
• category_ids (array of integers) — Categories to assign to the project

curl -X POST https://app.revelry.ai/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Product Launch",
    "overview": "Planning and execution for Q1 launch",
    "use_default_group": true,
    "category_ids": [1, 2]
  }'

Update Project

Endpoint: PUT /api/v1/projects/:id

All fields are optional on update — provide only the fields you want to change. If group_ids or category_ids are provided, they replace the existing assignments.

curl -X PUT https://app.revelry.ai/api/v1/projects/5 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Product Launch (Updated)",
    "overview": "Updated description"
  }'

Delete Project

Endpoint: DELETE /api/v1/projects/:id

curl -X DELETE https://app.revelry.ai/api/v1/projects/5 \
  -H "Authorization: Bearer YOUR_API_KEY"

Archive Project

Endpoint: POST /api/v1/projects/:id/archive

curl -X POST https://app.revelry.ai/api/v1/projects/5/archive \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Categories

Manage categories for organizing artifacts.

List Categories

Endpoint: GET /api/v1/categories

curl https://app.revelry.ai/api/v1/categories \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Category

Endpoint: POST /api/v1/categories

Required fields:

• name (string) — Category name
• group_ids (array of integers, at least one) — Groups that can access this category, or use_default_group: true to use the organization's default group

Optional fields:

• description (string) — Category description

curl -X POST https://app.revelry.ai/api/v1/categories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "description": "Engineering artifacts and documentation",
    "use_default_group": true
  }'

Get Category

Endpoint: GET /api/v1/categories/:id

curl https://app.revelry.ai/api/v1/categories/3 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Category

Endpoint: PUT /api/v1/categories/:id

All fields are optional on update — provide only the fields you want to change. If group_ids is provided, it replaces existing group assignments. Categories must always belong to at least one group.

curl -X PUT https://app.revelry.ai/api/v1/categories/3 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering (Updated)"
  }'

Delete Category

Endpoint: DELETE /api/v1/categories/:id

curl -X DELETE https://app.revelry.ai/api/v1/categories/3 \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Groups

Manage groups within your organization.

List Groups

Endpoint: GET /api/v1/groups

curl https://app.revelry.ai/api/v1/groups \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Group

Endpoint: POST /api/v1/groups

Required fields:

• name (string) — Group name

Optional fields:

• description (string) — Group description

curl -X POST https://app.revelry.ai/api/v1/groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "description": "Engineering team group"
  }'

Get Group

Endpoint: GET /api/v1/groups/:id

curl https://app.revelry.ai/api/v1/groups/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Group

Endpoint: PUT /api/v1/groups/:id

All fields are optional on update — provide only the fields you want to change.

curl -X PUT https://app.revelry.ai/api/v1/groups/1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering (Updated)",
    "description": "Updated description"
  }'

Delete Group

Endpoint: DELETE /api/v1/groups/:id

curl -X DELETE https://app.revelry.ai/api/v1/groups/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Add Group Member

Endpoint: POST /api/v1/groups/:id/members

Required fields:

• user_id (integer) — The user to add to the group

curl -X POST https://app.revelry.ai/api/v1/groups/1/members \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 42
  }'

Remove Group Member

Endpoint: DELETE /api/v1/groups/:id/members/:user_id

curl -X DELETE https://app.revelry.ai/api/v1/groups/1/members/42 \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Artifact Types

Manage artifact types.

List Artifact Types

Endpoint: GET /api/v1/artifact_types

curl https://app.revelry.ai/api/v1/artifact_types \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Artifact Type

Endpoint: POST /api/v1/artifact_types

Required fields:

• name (string, max 100 characters) — Artifact type name

The endpoint also accepts a category_id (integer), retained for backwards compatibility. A URL-friendly slug is auto-generated from the name.

curl -X POST https://app.revelry.ai/api/v1/artifact_types \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Technical Specification"
  }'

Update Artifact Type

Endpoint: PUT /api/v1/artifact_types/:id

All fields are optional on update — provide only the fields you want to change.

curl -X PUT https://app.revelry.ai/api/v1/artifact_types/2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Technical Specification (Updated)"
  }'

Delete Artifact Type

Endpoint: DELETE /api/v1/artifact_types/:id

curl -X DELETE https://app.revelry.ai/api/v1/artifact_types/2 \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Organizations (Super Admin)

Manage organizations. These endpoints require a super admin API key.

List Organizations

Endpoint: GET /api/v1/admin/organizations

curl https://app.revelry.ai/api/v1/admin/organizations \
  -H "Authorization: Bearer SUPER_ADMIN_API_KEY"

Create Organization

Creates a new organization along with an initial admin user.

Endpoint: POST /api/v1/admin/organizations

curl -X POST https://app.revelry.ai/api/v1/admin/organizations \
  -H "Authorization: Bearer SUPER_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": {
      "name": "Acme Corp"
    },
    "user": {
      "email": "admin@acme.com"
    }
  }'

Get Organization

Endpoint: GET /api/v1/admin/organizations/:id

curl https://app.revelry.ai/api/v1/admin/organizations/10 \
  -H "Authorization: Bearer SUPER_ADMIN_API_KEY"

Update Organization

Endpoint: PUT /api/v1/admin/organizations/:id

curl -X PUT https://app.revelry.ai/api/v1/admin/organizations/10 \
  -H "Authorization: Bearer SUPER_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation"
  }'

Deactivate Organization

Endpoint: DELETE /api/v1/admin/organizations/:id

This deactivates the organization rather than permanently deleting it.

curl -X DELETE https://app.revelry.ai/api/v1/admin/organizations/10 \
  -H "Authorization: Bearer SUPER_ADMIN_API_KEY"

---

Error Responses

Status Code	Description
400	Invalid request parameters
401	Invalid or missing API key
403	Insufficient permissions
404	Resource not found
422	Validation failed
429	Rate limit exceeded

---

Next Steps

• API Usage Guide - Artifact generation via API
• Workflows API - Programmatic workflow execution
• Managing API Keys - Set up authentication
• OpenAPI Documentation - Full API specification