Skip to main content
Create a new project within an organization. The authenticated user automatically becomes the owner of the newly created project.

​
Path Parameters

​
org_id
string
required
Organization ID where the project will be created. Must be a valid UUID.

​
Request Body

​
body
object
required
Project details to create.
​
name
string
required
Unique name/slug for the project within the organization. Must be lowercase, alphanumeric with hyphens. Used in URLs and API calls.Example: data-platform, mobile-app
​
title
string
required
Human-readable display name for the project. Can contain spaces and special characters.Example: Data Platform, Mobile Application
​
org_id
string
required
Organization ID where the project will be created. Should match the path parameter.
​
metadata
object
Custom metadata for the project. Can contain any valid JSON structure. Must comply with the project metadata schema if validation is enabled.Example: {"team": "engineering", "department": "data", "cost_center": "cc-1234"}

​
Response

​
project
object
The newly created project object.
​
id
string
Unique identifier for the project (UUID format).
​
name
string
Unique name/slug for the project.
​
title
string
Human-readable display name for the project.
​
org_id
string
ID of the organization this project belongs to.
​
metadata
object
Custom metadata associated with the project.
​
created_at
timestamp
Timestamp when the project was created (RFC3339 format).
​
updated_at
timestamp
Timestamp when the project was last updated (RFC3339 format).
​
members_count
integer
Number of members in the project. Will be 1 for newly created projects (the creator).
curl -X POST 'https://api.frontier.example.com/v1beta1/organizations/9f256f86-d3c4-4a6e-b89a-1e9a23c5d78e/projects' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "body": {
      "name": "data-platform",
      "title": "Data Platform",
      "org_id": "9f256f86-d3c4-4a6e-b89a-1e9a23c5d78e",
      "metadata": {
        "team": "engineering",
        "department": "data"
      }
    }
  }'

​
Response Example

{
  "project": {
    "id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
    "name": "data-platform",
    "title": "Data Platform",
    "org_id": "9f256f86-d3c4-4a6e-b89a-1e9a23c5d78e",
    "metadata": {
      "team": "engineering",
      "department": "data"
    },
    "created_at": "2024-03-03T10:30:00Z",
    "updated_at": "2024-03-03T10:30:00Z",
    "members_count": 1
  }
}

​
Error Responses

​
code
string
Error code indicating the type of error.
​
message
string
Human-readable error message.

​
Common Errors

  • 400 Bad Request: Invalid request body or missing required fields
    • Invalid project name format (must be lowercase alphanumeric with hyphens)
    • Invalid organization ID format
    • Metadata doesn’t match the required schema
    • Missing required fields (name, title, or org_id)
  • 401 Unauthenticated: Invalid or missing authentication token
  • 404 Not Found: Organization not found
  • 409 Conflict: Project with the same name already exists in the organization
  • 500 Internal Server Error: Server encountered an unexpected error

​
Notes

  • The authenticated user automatically becomes the project owner with full permissions
  • Project names must be unique within an organization (but can be duplicated across different organizations)
  • The project is created in enabled state by default
  • An audit log entry is created for the project creation event
  • Default owner role and permissions are automatically set up for the creator
  • A relation is automatically created linking the project to its organization

Build docs developers (and LLMs) love

Get started for freeTalk to us