Skip to content

api.md

Latest commit

 

History

History
123 lines (97 loc) · 4.16 KB

api.md

File metadata and controls

123 lines (97 loc) · 4.16 KB
Raw
layout default
title API Reference

REST API for programmatic access to ConvoArena experiment management.

ConvoArena's API is built on Deliberate Lab's, so the code still uses Deliberate Lab names: the Python package is deliberate_lab and the API key variable is DL_API_KEY.

Authentication

All API requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Creating an API Key

  1. Log into the ConvoArena web interface
  2. Navigate to Settings (top right menu)
  3. Scroll to the ConvoArena API Access section
  4. Click + Create ConvoArena API Key
  5. Enter a descriptive name for your key
  6. Copy the generated key immediately - it will only be shown once

Important: Store your API key securely. You cannot retrieve it after closing the creation dialog.

Managing API Keys

In the ConvoArena API Access section of the Settings page, you can:

  • View all your API keys
  • See when each key was created and last used
  • Revoke keys you no longer need

Rate Limiting

Requests are rate-limited per API key, and return HTTP 429 when the limit is exceeded. You can customize the limit for your deployment with windowMs and max in functions/src/dl_api/dl_api.endpoints.ts, then redeploy the functions.

Python Client

A Python client with fully-typed Pydantic models is available:

pip install git+https://github.com/CornellNLP/ConvoArena.git#subdirectory=scripts
import deliberate_lab as dl

# Uses the DL_API_KEY environment variable
client = dl.Client(base_url="https://us-central1-<your-project-id>.cloudfunctions.net/api/v1")
experiments = client.list_experiments()
data = client.export_experiment("experiment-id")

Always pass base_url with your own project ID. The client's built-in env="prod" and env="dev" URLs point to upstream Deliberate Lab's servers.

New to the API? Check out Codelab 1: Create an experiment via API for a hands-on tutorial, then Codelab 2: ConvoArena features via API for assistants, multi-step prompts, should-respond prompts and simulations.

What ConvoArena adds

ConvoArena's API extends the Deliberate Lab API with:

  • Batch cohort creation: POST /experiments/{experimentId}/cohorts/batch creates many cohorts in one request.
  • Private assistants: agentAssistants when creating or updating an experiment. See Add private assistants.
  • Scheduled availability: unlockTimeMs (when the experiment opens) and unlockDurationMs (how long it stays open) when creating an experiment.
  • Prompt fields: assistant-only prompt blocks and the should-respond prompt, plus fields for auditing experiments (interventionProbability, interventionType, transformPrompt). See Prompt blocks and Control when agents intervene.
  • Python client: create_simulation() creates an experiment and its cohorts in one call, and get_completed_experiment_data() returns the export only once every participant has finished. create_experiment() also accepts agent_assistants, unlock_time_ms and unlock_duration_ms.

API Reference

<style> /* Override Jekyll default styles for Swagger UI */ .content-wrapper { max-width: 100%; }

#swagger-ui code { all: revert !important; } </style>

<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script> <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script> <script> window.onload = function () { const ui = SwaggerUIBundle({ url: '{{ site.baseurl }}/assets/api/openapi.yaml', dom_id: '#swagger-ui', deepLinking: true, presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset], layout: 'BaseLayout', defaultModelsExpandDepth: 1, defaultModelExpandDepth: 0, docExpansion: 'list', filter: true, tryItOutEnabled: true, }); window.ui = ui; }; </script>