Skip to main content

Projects

A project is the ownership and URL boundary for datasets, jobs, hosted aliases, and inference. Project routes are authenticated and owner-only; public or shared hosted-model access is granted at the alias, not by making a project public.

Endpoints​

GET  /api/v1/projects
POST /api/v1/projects
GET  /api/v1/projects/{owner_slug}/{project_slug}
PUT  /api/v1/projects/{owner_slug}/{project_slug}
GET  /api/v1/projects/{owner_slug}/{project_slug}/tags
POST /api/v1/projects/{owner_slug}/{project_slug}/archive
POST /api/v1/projects/{owner_slug}/{project_slug}/unarchive

Create a text project with:

{
  "name": "Support",
  "description": "Support conversations and models",
  "type": "text",
  "inference_save_percent": 0.0
}

Despite its historical name, inference_save_percent is a probability fraction from 0 through 1: 0.25 samples roughly one quarter of eligible owner-originated inference requests. Shared and public callers' prompts are never auto-saved into the owner's dataset.

Project types​

A project's type is chosen when it is created and never changes:

  • text: chat datasets, fine-tuned text-generation models, chat and text completions.
  • embedding: datasets of Training pairs, fine-tuned embedding models, /embeddings, the embedding Playground, Search and Search feedback. Start with the Quickstart for embeddings.

Both types share the same routes for projects, datasets, training jobs, hosted models and billing; a route that only one type supports answers the other with 409 project_capability_mismatch. GET /api/v1/projects/capabilities lists the types you can create and what each supports. inference_save_percent applies to text projects only: embedding calls are never saved.

Listing and summaries​

GET /api/v1/projects always returns {projects,next_cursor,total_count}. Use limit (default 25, maximum 100) and cursor directly. Cursors belong to your account and archive filter. Archived projects are excluded unless include_archived=true. Project cards include bounded counts for chats, jobs, and hosted models.

Account-wide reads are separate:

  • GET /api/v1/dashboard returns a fixed-size global summary.
  • GET /api/v1/models returns accessible hosted aliases across projects with cursor pagination.
  • GET /api/v1/activity returns the owner's cursor-paginated job and alias creation history.

Archive instead of delete​

Archiving is idempotent and reversible. It retains chats, immutable training records, aliases, artifacts, and billing history, while making the project read-only. Archive is refused with 409 and detail.code = "project_has_nonterminal_work" while training is pending, running, or awaiting cancellation. Cancel and settle that work first.

Archived projects do not consume an active-project slot. Unarchive can still return 409 if restoring the project would exceed the account quota. Inference against an archived project's OpenAI surface returns 404 with error.code = "project_archived" and no Retry-After.

Project creation accepts only text (the default) or embedding. Historical multimodal projects can remain readable, but that type is not offered for creation.