Projects API — MIOSA Docs

A Project is the app, website, lead magnet, document, workflow, or customer build inside a workspace. Projects own sandboxes, computers, deployments, databases, storage buckets, volumes, functions, jobs, auth configuration, integrations, and custom domains.

Base path: /api/v1/projects

Endpoints

Method	Path	Description
`GET`	`/projects`	List projects for the organization
`POST`	`/projects`	Create a project inside a workspace
`GET`	`/projects/{id}`	Get one project
`PATCH`	`/projects/{id}`	Update a project
`GET`	`/projects/{id}/preview-domain`	Read the project preview domain
`PUT`	`/projects/{id}/preview-domain`	Set the project preview domain
`DELETE`	`/projects/{id}/preview-domain`	Clear the project preview domain
`GET`	`/projects/{id}/preview-domain/verify`	Check DNS readiness
`GET`	`/workspaces/{id}/projects`	List projects in one workspace

List Projects

GET /api/v1/projects

Query Parameters

Parameter	Type	Description
`workspace_id`	UUID	Limit results to one workspace

Response - `200 OK`

{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "tenant_id": "tnt_abc123",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "external_workspace_id": "clinic_123",
      "external_project_id": "project_789",
      "name": "Lead Magnet",
      "slug": "lead-magnet",
      "description": null,
      "metadata": {},
      "settings": {},
      "created_at": "2026-05-18T10:00:00Z",
      "updated_at": "2026-05-18T10:00:00Z"
    }
  ],
  "total": 1
}

curl "https://api.miosa.ai/api/v1/projects?workspace_id=550e8400-e29b-41d4-a716-446655440000" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Create a Project

POST /api/v1/projects

A project must belong to a workspace. Supply one of workspace_id, workspace_slug, or external_workspace_id.

Request Body

Field	Type	Required	Description
`workspace_id`	UUID	Conditional	Existing MIOSA workspace ID
`workspace_slug`	string	Conditional	Existing workspace slug
`external_workspace_id`	string	Conditional	Your external workspace/customer ID
`name`	string	Yes	Human-readable project name
`slug`	string	No	URL-safe identifier. Auto-derived from `name` if omitted.
`external_project_id`	string	No	Your project/app/document ID
`description`	string	No	Optional description
`metadata`	object	No	Caller metadata stored on the project

Example

curl -X POST https://api.miosa.ai/api/v1/projects 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "workspace_slug": "dr-smith-clinic",
    "name": "Lead Magnet",
    "slug": "lead-magnet",
    "external_workspace_id": "clinic_123",
    "external_project_id": "project_789"
  }'

Response - `201 Created`

Full project object.

Errors

Status	Code	Cause
400	`WORKSPACE_REQUIRED`	No `workspace_id`, `workspace_slug`, or `external_workspace_id` was supplied
404	`WORKSPACE_NOT_FOUND`	Workspace selector did not resolve inside the organization
422	`VALIDATION_FAILED`	Name, slug, or external project ID failed validation

Get a Project

GET /api/v1/projects/{id}

Returns one project if it belongs to the authenticated organization.

curl https://api.miosa.ai/api/v1/projects/{id} 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Update a Project

PATCH /api/v1/projects/{id}

Request Body

Field	Type	Description
`name`	string	New display name
`slug`	string	New URL-safe slug, unique inside the workspace
`description`	string	New description (`null` to clear)
`external_project_id`	string	Your project/app/document ID
`external_workspace_id`	string	Your customer/workspace ID
`metadata`	object	Replacement metadata map
`settings`	object	Replacement settings map. Prefer the preview-domain endpoint for domain changes.

curl -X PATCH https://api.miosa.ai/api/v1/projects/{id} 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"name": "Summer Lead Magnet"}'

Use Projects on Resource Create

Most create endpoints accept the same ownership fields:

{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440001",
  "external_workspace_id": "clinic_123",
  "external_project_id": "project_789"
}

You can use slugs instead of UUIDs:

{
  "workspace_slug": "dr-smith-clinic",
  "workspace_name": "Dr. Smith Clinic",
  "project_slug": "lead-magnet",
  "project_name": "Lead Magnet"
}

This applies to sandboxes, computers, deployments, databases, storage buckets, volumes, edge functions, cron jobs, project auth, and integrations. Derived records inherit ownership automatically.

Project Preview Domain

PUT /api/v1/projects/{id}/preview-domain

Sets a project-level base domain for generated URLs. This overrides the workspace preview domain and organization preview domain for resources in this project.

curl -X PUT https://api.miosa.ai/api/v1/projects/{id}/preview-domain 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"preview_domain":"program.drsmithclinic.com"}'

Response:

{
  "scope": "project",
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "preview_domain": "program.drsmithclinic.com",
  "effective_domain": "program.drsmithclinic.com",
  "status": "pending_dns",
  "dns_status": "pending",
  "url_examples": {
    "default_preview": "https://<slug>.program.drsmithclinic.com",
    "port_preview": "https://3000-<slug>.sandbox.program.drsmithclinic.com",
    "deployment": "https://<deployment-slug>.program.drsmithclinic.com"
  }
}

Required DNS records:

Record type	Name	Value
`CNAME`	`*`	`proxy.miosa.ai`
`CNAME`	`*.sandbox`	`proxy.miosa.ai`

Verify:

curl https://api.miosa.ai/api/v1/projects/{id}/preview-domain/verify 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Clear and inherit from the workspace/organization fallback:

curl -X DELETE https://api.miosa.ai/api/v1/projects/{id}/preview-domain 
  -H "Authorization: Bearer $MIOSA_API_KEY"