API Usage Guide

The Revelry Ai API enables programmatic integration with Revelry Ai for custom client applications. This guide provides an overview of the Revelry Ai API and how to use it.

When to Use the API

Use the API for:

Custom client applications
Integration with existing systems
Programmatic Artifact generation
Automated processes outside of the platform
Building on top of Revelry Ai capabilities
Long-running generation tasks (use async + webhooks)
Parallel Artifact generation at scale

Use Chat instead for:

Interactive refinement
Dynamic tool execution with MCP
Human-in-the-loop generation
Exploratory work

To embed a conversation in your own application, with streaming replies and tool use, see the Chat API.

Authentication

All API requests require authentication via API key. Both Organization and Personal API keys work with every endpoint. To set one up, see Managing API Keys.

To authenticate requests with the Revelry Ai API, include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limiting

API Requests are rate-limited to prevent abuse. If your requests exceed the rate limit, you will receive a 429 - Too Many Requests response along with a Retry-After header indicating the number of seconds to wait until retrying your request.

Base URL

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

Core Endpoints

Artifact Generation Modes:

Streaming - Real-time SSE responses (endpoint #1 below)
Non-Streaming - Single response with complete result (endpoint #2 below)
Async - Fire-and-forget with webhook notifications (see Async Generation & Webhooks)

V2 API with Tool Calling: The V2 API supports MCP tool calling during artifact generation, and adds the Chat API for full conversations. See the OpenAPI Documentation for V2 endpoint details.

1. Generate Artifact (Streaming)

Endpoint: POST /api/v1/artifact_types/:artifact_type_slug/artifacts/stream

Generate Artifacts with real-time streaming responses using Server-Sent Events (SSE).

Request:

curl -X POST "https://app.revelry.ai/api/v1/artifact_types/prd/artifacts/stream?project_id=456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": 123,
    "inputs": [
      { "name": "product_name", "value": "My Product" },
      { "name": "feature_description", "value": "User authentication system" }
    ]
  }'

Response (SSE Stream):

event: chunk
data: {"content": "# Product Requirements", "done": false}

event: chunk
data: {"content": " Document\\n\\n", "done": false}

event: chunk
data: {"content": "## Overview\\n", "done": false}

event: done
data: {"artifact_id": "artifact-789", "done": true}

Parameters:

project_id (query, required) - Project context
skill_id (body, required*) - The Skill to use for generation. *For backward compatibility the deprecated prompt_template_id is still accepted in its place.
inputs (body, required) - Array of { "name", "value" } objects supplying the Skill's user inputs (pass an empty array [] if the Skill has none)
name (body, optional) - A specific artifact name (otherwise the model generates one)
model_configuration_id (body, optional) - Override the model used for generation

Response Events:

chunk - Partial content as it's generated
done - Generation complete with Artifact ID

2. Generate Artifact (Non-Streaming)

Endpoint: POST /api/v1/artifact_types/:artifact_type_slug/artifacts

Generate Artifacts with a single response containing the complete result.

Request:

curl -X POST "https://app.revelry.ai/api/v1/artifact_types/prd/artifacts?project_id=456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": 123,
    "inputs": [
      { "name": "product_name", "value": "My Product" },
      { "name": "feature_description", "value": "User authentication system" }
    ]
  }'

Uses the same parameters as the streaming endpoint above. Add "fire_and_forget": true to the body to generate in the background and return immediately (see Async Generation & Webhooks).

Response:

{
  "artifact": {
    "id": 789,
    "name": "Product Requirements Document",
    "content": "# Product Requirements Document\\n\\n## Overview...",
    "manually_edited": false,
    "notes": null,
    "share_token": "share-token",
    "chat_history": []
  },
  "url": "https://app.revelry.ai/..."
}

When to use:

You want the complete Artifact before proceeding
You don't need real-time feedback
Simpler implementation without SSE handling

3. Refine Artifact (Streaming)

Endpoint: POST /api/v1/artifact_types/:artifact_type_slug/artifacts/:artifact_id/refine_stream

Refine existing Artifacts with streaming responses.

Request:

curl -X POST https://app.revelry.ai/api/v1/artifact_types/prd/artifacts/artifact-789/refine_stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refine_prompt": "Add a section about security requirements"
  }'

Response (SSE Stream):

event: chunk
data: {"content": "## Security Requirements\\n\\n", "done": false}

event: chunk
data: {"content": "- Authentication via OAuth 2.0\\n", "done": false}

event: done
data: {"artifact_id": "artifact-789", "done": true}

Use cases:

Iterative improvements
Adding sections or details
Modifying tone or format
Incorporating feedback

4. Refine Artifact (Non-Streaming)

Endpoint: POST /api/v1/artifact_types/:artifact_type_slug/artifacts/:artifact_id/refine

Refine Artifacts with a single response.

Request:

curl -X POST https://app.revelry.ai/api/v1/artifact_types/prd/artifacts/artifact-789/refine \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refine_prompt": "Add a section about security requirements"
  }'

Response:

{
  "artifact": {
    "id": 789,
    "name": "Product Requirements Document",
    "content": "# Product Requirements Document\\n\\n...\\n\\n## Security Requirements...",
    "manually_edited": false,
    "notes": null,
    "share_token": "share-token",
    "chat_history": []
  },
  "url": "https://app.revelry.ai/..."
}

Async Artifact Generation & Webhooks

For long-running Artifact Generation tasks, you can use async (fire-and-forget) generation combined with webhooks to receive notifications when Artifacts are complete.

When to Use Async Artifact Generation

Use Async Generation when:

You don't want to maintain an open connection during generation
You're generating multiple Artifacts in parallel
Your Artifacts take a long time to generate
You prefer event-driven architecture over polling

Use Streaming/Non-Streaming Artifact Generation instead when:

You need immediate results
You want real-time progress feedback
Generation is typically quick (< 30 seconds)

How Async Artifact Generation Works

Configure a webhook for your project (receives Artifact events)
Make an async generation request with "fire_and_forget": true in the body
Receive an api_async_create_event_id immediately in the response (the request doesn't wait)
Webhook receives a notification when the Artifact is complete (or fails)
Match api_async_create_event_id from the webhook payload to your original request

Step 1: Configure Webhooks

Before using Async Artifact Generation, set up a webhook endpoint for your project.

Webhook Configuration:

Navigate to Project Settings > Webhooks in Revelry Ai
Add your webhook URL endpoint
Select events: artifact_generated, artifact_refined, artifact_generation_failed
Save webhook configuration

Webhook Payload Format:

Every webhook is delivered as a JSON body with an event_name and an event_data object. When an Artifact is generated, your webhook receives:

{
  "event_name": "artifact_generated",
  "event_data": {
    "name": "Product Requirements Document",
    "artifact_id": 789,
    "artifact_type_slug": "prd",
    "project_id": 456,
    "api_async_create_event_id": "b3f1c2a4-...",
    "chat_id": 12
  }
}

The chat_id field is included only when the Artifact has an associated chat. Refinements emit the same shape under the artifact_refined event.

If generation fails:

{
  "event_name": "artifact_generation_failed",
  "event_data": {
    "api_async_create_event_id": "b3f1c2a4-...",
    "project_id": 456,
    "artifact_type_slug": "prd"
  }
}

Key Fields:

event_name - The event type (artifact_generated, artifact_refined, or artifact_generation_failed)
event_data.artifact_id - ID of the generated Artifact (success only)
event_data.api_async_create_event_id - Correlation ID matching the one returned by your original request

Step 2: Make Async Artifact Generation Request

Endpoint: POST /api/v1/artifact_types/:artifact_type_slug/artifacts

Add "fire_and_forget": true to your request:

curl -X POST "https://app.revelry.ai/api/v1/artifact_types/prd/artifacts?project_id=456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": 123,
    "fire_and_forget": true,
    "inputs": [
      { "name": "product_name", "value": "My Product" },
      { "name": "feature_description", "value": "User authentication system" }
    ]
  }'

Immediate Response:

{
  "message": "Artifact is being generated. An event will be emitted via Webhooks when it is ready.",
  "api_async_create_event_id": "b3f1c2a4-..."
}

Response Fields:

message - Confirmation that generation has started
api_async_create_event_id - Store this; the matching webhook event carries the same value

Step 3: Handle Webhook Notification

Implement a webhook handler in your application that:

For artifact_generated events:

Extract artifact_id and api_async_create_event_id from event_data
Match api_async_create_event_id to your original request
Fetch the complete Artifact via GET /artifacts/:id
Process the Artifact (update database, notify users, etc.)
Return HTTP 200 to acknowledge receipt

For artifact_generation_failed events:

Extract api_async_create_event_id from event_data
Match it to your original request and handle the failure (retry, alert, log for investigation)
Return HTTP 200 to acknowledge receipt

Security:

Use HTTPS endpoints only
Validate payload structure before processing
Implement authentication/authorization in your webhook handler

Step 4: Match the Event to Your Request

Store the api_async_create_event_id returned from your async request, alongside any context you need (project, user, timestamp).
When a webhook arrives, read event_data.api_async_create_event_id.
Look up your stored request by that ID.
Process the Artifact with full context (for success events, fetch it via GET /artifacts/:id).

Best Practices for Async Artifact Generation

1. Track the Async Event ID

Store the api_async_create_event_id from each async response
Persist it with your request context for reliable matching when the webhook arrives

2. Implement Idempotent Webhook Handlers

Webhooks may be delivered more than once
Check if an event was already processed before taking action (track handled api_async_create_event_id values)
Return 200 OK even if duplicate

3. Handle Webhook Failures Gracefully

Set reasonable timeouts for webhook responses
Implement retry logic with exponential backoff
Monitor webhook delivery success rates

4. Secure Your Webhooks

Use HTTPS endpoints only
Validate payload structure before processing
Rate limit webhook endpoint
Implement authentication/authorization in your webhook handler

5. Monitor Pending Requests

Set timeouts for async requests (e.g., 10 minutes)
Clean up stale pending requests periodically
Alert on requests that never complete
Implement background job to remove requests older than timeout threshold

Async vs Streaming vs Non-Streaming Artifact Generation

Approach	Connection	Use Case	Complexity
Async + Webhooks	Fire-and-forget	Long-running, parallel tasks	High
Streaming	Keep-alive (SSE)	Real-time feedback	Medium
Non-Streaming	Wait for response	Quick generation	Low

Example Decision Tree:

Generation takes > 2 minutes?
  → YES: Use Async + Webhooks
  → NO: Continue...

Need real-time progress updates?
  → YES: Use Streaming
  → NO: Use Non-Streaming

Additional Endpoints

List Artifact Types

Endpoint: GET /api/v1/artifact_types

Get available Artifact Types for your organization.

Response:

{
  "artifact_types": [
    {
      "slug": "prd",
      "name": "Product Requirements Document",
      "description": "Detailed product specifications"
    },
    {
      "slug": "user-story",
      "name": "User Story",
      "description": "BDD-style user stories"
    }
  ]
}

List Skills

Endpoint: GET /api/v1/artifact_types/:artifact_type_slug/skills

Get the available Skills for an Artifact Type. (The earlier .../prompt_templates path still works but is deprecated.)

Response:

{
  "skills": [
    {
      "id": 123,
      "name": "Standard PRD",
      "content": "Generate a PRD for {custom.product_name}...",
      "description": "Generate comprehensive product requirements",
      "custom_variables": [
        { "name": "product_name", "description": "The product name", "type": "text" },
        { "name": "feature_description", "description": "What the feature does", "type": "text" }
      ]
    }
  ]
}

Get Artifact

Endpoint: GET /api/v1/artifact_types/:artifact_type_slug/artifacts/:artifact_id

Retrieve a specific Artifact.

Response:

{
  "artifact": {
    "id": 789,
    "name": "Product Requirements Document",
    "content": "# Product Requirements Document...",
    "manually_edited": false,
    "notes": null,
    "share_token": "share-token",
    "chat_history": []
  }
}

Delete Artifact

Endpoint: DELETE /api/v1/artifact_types/:artifact_type_slug/artifacts/:artifact_id

Delete an Artifact.

Response:

{
  "message": "Artifact deleted successfully"
}

Upload Documents

Endpoint: POST /api/v1/data_center/documents

Upload documents to your Knowledge Base programmatically. The request is multipart/form-data with a document file field, plus either group_ids[] (one or more group IDs) or use_default_group=true to assign the document to the organization's default group.

Request:

curl -X POST https://app.revelry.ai/api/v1/data_center/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "document=@/path/to/document.pdf" \
  -F "group_ids[]=1"

Response:

{
  "document": {
    "id": 456,
    "name": "document.pdf",
    "processing_status": "queued",
    "embedding_error": null,
    "ocr_error": null,
    "group_ids": [1]
  }
}

Error Handling

HTTP Status Codes

200 OK - Request successful
201 Created - Resource created
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
404 Not Found - Resource doesn't exist
422 Unprocessable Entity - Validation failed
500 Internal Server Error - Server error

Error Response Format

{
  "error": {
    "message": "Invalid prompt template ID",
    "code": "invalid_template",
    "details": {
      "prompt_template_id": ["does not exist"]
    }
  }
}

Best Practices

API Key Security

Never expose API keys in client-side code
Store securely in environment variables
Rotate regularly for security
Use separate keys for dev/staging/production

Error Handling

Always check HTTP status codes
Parse error messages for details
Implement retry logic for transient failures
Log errors for debugging

Streaming Best Practices

Use streaming for real-time feedback
Handle SSE reconnection
Parse chunks incrementally
Buffer content appropriately

Workflows API - Programmatically trigger and manage workflow runs
Management API - CRUD operations for projects, categories, artifact types, and organizations

Future Features

Coming soon to the API:

GraphQL Endpoint - More flexible querying

Complete API Reference

For the full API specification including all endpoints, parameters, and response schemas:

OpenAPI Documentation

Next Steps

Managing API Keys: Managing API Keys
Understand Artifacts: Artifacts Overview
Compare with Chat: When to use each approach
Automate with Workflows: Workflows Documentation

When to Use the API​

Authentication​

Rate Limiting​

Base URL​

Core Endpoints​

1. Generate Artifact (Streaming)​

2. Generate Artifact (Non-Streaming)​

3. Refine Artifact (Streaming)​

4. Refine Artifact (Non-Streaming)​

Async Artifact Generation & Webhooks​

When to Use Async Artifact Generation​

How Async Artifact Generation Works​

Step 1: Configure Webhooks​

Step 2: Make Async Artifact Generation Request​

Step 3: Handle Webhook Notification​

Step 4: Match the Event to Your Request​

Best Practices for Async Artifact Generation​

Async vs Streaming vs Non-Streaming Artifact Generation​

Additional Endpoints​

List Artifact Types​

List Skills​

Get Artifact​

Delete Artifact​

Upload Documents​

Error Handling​

HTTP Status Codes​

Error Response Format​

Best Practices​

API Key Security​

Error Handling​

Streaming Best Practices​

Related API Documentation​

Future Features​

Complete API Reference​

Next Steps​

When to Use the API

Authentication

Rate Limiting

Base URL

Core Endpoints

1. Generate Artifact (Streaming)

2. Generate Artifact (Non-Streaming)

3. Refine Artifact (Streaming)

4. Refine Artifact (Non-Streaming)

Async Artifact Generation & Webhooks

When to Use Async Artifact Generation

How Async Artifact Generation Works

Step 1: Configure Webhooks

Step 2: Make Async Artifact Generation Request

Step 3: Handle Webhook Notification

Step 4: Match the Event to Your Request

Best Practices for Async Artifact Generation

Async vs Streaming vs Non-Streaming Artifact Generation

Additional Endpoints

List Artifact Types

List Skills

Get Artifact

Delete Artifact

Upload Documents

Error Handling

HTTP Status Codes

Error Response Format

Best Practices

API Key Security

Error Handling

Streaming Best Practices

Related API Documentation

Future Features

Complete API Reference

Next Steps