---
title: "Create a Workspace"
method: POST
path: "/v2/gen-ai/workspaces"
tags: ["GenAIAPI"]
---

# Create a Workspace

`POST /v2/gen-ai/workspaces`

To create a new workspace, send a POST request to `/v2/gen-ai/workspaces`. The response body contains a JSON object with the newly created workspace object.

## Request body

- ApiCreateWorkspaceInputPublic
  - `name` string
  - `description` string
  - `agent_uuids` string[]

## Response `200`

A successful response.

- ApiCreateWorkspaceOutput
  - `workspace` ApiWorkspace
    - `uuid` string
    - `name` string
    - `description` string
    - `created_by_email` string
    - `created_by` string, uint64
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `deleted_at` string, date-time
    - `agents` ApiAgent[]
      - `uuid` string
      - `name` string
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `url` string
      - `instruction` string — Agent instruction. Instructions help your agent to perform its job effectively. See [Write Effective Agent Instructions](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/#agent-instructions) for best practices.
      - `description` string
      - `model` ApiModel
        - `uuid` string
        - `name` string
        - `inference_name` string
        - `version` ApiModelVersion
          - `major` integer
          - `minor` integer
          - `patch` integer
        - `inference_version` string
        - `url` string
        - `is_foundational` boolean
        - `upload_complete` boolean
        - `created_at` string, date-time
        - `updated_at` string, date-time
        - `metadata` object
        - `parent_uuid` string
        - `agreement` ApiAgreement
          - `uuid` string
          - `name` string
          - `description` string
          - `url` string
        - `provider` 'MODEL_PROVIDER_DIGITALOCEAN' | 'MODEL_PROVIDER_ANTHROPIC' | 'MODEL_PROVIDER_OPENAI'
        - `usecases` ApiModelUsecase[]
      - `deployment` ApiDeployment
        - `uuid` string
        - `name` string
        - `url` string
        - `status` 'STATUS_UNKNOWN' | 'STATUS_WAITING_FOR_DEPLOYMENT' | 'STATUS_DEPLOYING' | 'STATUS_RUNNING' | 'STATUS_FAILED' | 'STATUS_WAITING_FOR_UNDEPLOYMENT' | 'STATUS_UNDEPLOYING' | 'STATUS_UNDEPLOYMENT_FAILED' | 'STATUS_DELETED'
        - `visibility` 'VISIBILITY_UNKNOWN' | 'VISIBILITY_DISABLED' | 'VISIBILITY_PLAYGROUND' | 'VISIBILITY_PUBLIC' | 'VISIBILITY_PRIVATE'
        - `created_at` string, date-time
        - `updated_at` string, date-time
      - `functions` ApiAgentFunction[]
        - `uuid` string
        - `name` string
        - `description` string
        - `api_key` string
        - `url` string
        - `input_schema` object
        - `output_schema` object
        - `created_at` string, date-time
        - `updated_at` string, date-time
        - `faas_namespace` string
        - `faas_name` string
        - `created_by` string, uint64
      - `child_agents` ApiAgent[]
      - `parent_agents` ApiAgent[]
      - `knowledge_bases` ApiKnowledgeBase[]
        - `uuid` string
        - `name` string
        - `created_at` string, date-time
        - `updated_at` string, date-time
        - `tags` string[]
        - `region` string
        - `embedding_model_uuid` string
        - `project_id` string
        - `database_id` string
        - `last_indexing_job` ApiIndexingJob
          - `uuid` string
          - `knowledge_base_uuid` string
          - `data_source_uuids` string[]
          - `created_at` string, date-time
          - `updated_at` string, date-time
          - `started_at` string, date-time
          - `finished_at` string, date-time
          - `phase` 'BATCH_JOB_PHASE_UNKNOWN' | 'BATCH_JOB_PHASE_PENDING' | 'BATCH_JOB_PHASE_RUNNING' | 'BATCH_JOB_PHASE_SUCCEEDED' | 'BATCH_JOB_PHASE_FAILED' | 'BATCH_JOB_PHASE_ERROR' | 'BATCH_JOB_PHASE_CANCELLED'
          - `total_datasources` integer
          - `completed_datasources` integer
          - `tokens` integer
          - `status` 'INDEX_JOB_STATUS_UNKNOWN' | 'INDEX_JOB_STATUS_PARTIAL' | 'INDEX_JOB_STATUS_IN_PROGRESS' | 'INDEX_JOB_STATUS_COMPLETED' | 'INDEX_JOB_STATUS_FAILED' | 'INDEX_JOB_STATUS_NO_CHANGES' | 'INDEX_JOB_STATUS_PENDING'
        - `added_to_agent_at` string, date-time
        - `user_id` string, int64
        - `is_public` boolean
      - `api_keys` ApiAgentAPIKey[]
        - `api_key` string
      - `k` integer
      - `temperature` number, float
      - `top_p` number, float
      - `max_tokens` integer
      - `tags` string[]
      - `project_id` string
      - `route_name` string
      - `if_case` string
      - `route_created_by` string, uint64
      - `route_uuid` string
      - `region` string
      - `chatbot` ApiChatbot
        - `name` string
        - `primary_color` string
        - `secondary_color` string
        - `starting_message` string
        - `button_background_color` string
        - `logo` string
      - `route_created_at` string, date-time
      - `user_id` string, uint64
      - `guardrails` ApiAgentGuardrail[]
        - `uuid` string
        - `priority` integer
        - `is_attached` boolean
        - `created_at` string, date-time
        - `updated_at` string, date-time
        - `agent_uuid` string
        - `guardrail_uuid` string
        - `name` string
        - `description` string
        - `default_response` string
        - `is_default` boolean
        - `type` 'GUARDRAIL_TYPE_UNKNOWN' | 'GUARDRAIL_TYPE_JAILBREAK' | 'GUARDRAIL_TYPE_SENSITIVE_DATA' | 'GUARDRAIL_TYPE_CONTENT_MODERATION'
        - `metadata` object
      - `chatbot_identifiers` ApiAgentChatbotIdentifier[]
        - `agent_chatbot_identifier` string
      - `api_key_infos` ApiAgentAPIKeyInfo[]
        - `secret_key` string
        - `name` string
        - `uuid` string
        - `created_by` string, uint64
        - `created_at` string, date-time
        - `deleted_at` string, date-time
      - `template` ApiAgentTemplate
        - `uuid` string
        - `name` string
        - `description` string
        - `model` ApiModel
          - `uuid` string
          - `name` string
          - `inference_name` string
          - `version` ApiModelVersion
            - `major` integer
            - `minor` integer
            - `patch` integer
          - `inference_version` string
          - `url` string
          - `is_foundational` boolean
          - `upload_complete` boolean
          - `created_at` string, date-time
          - `updated_at` string, date-time
          - `metadata` object
          - `parent_uuid` string
          - `agreement` ApiAgreement
            - `uuid` string
            - `name` string
            - `description` string
            - `url` string
          - `provider` 'MODEL_PROVIDER_DIGITALOCEAN' | 'MODEL_PROVIDER_ANTHROPIC' | 'MODEL_PROVIDER_OPENAI'
          - `usecases` ApiModelUsecase[]
        - `created_at` string, date-time
        - `updated_at` string, date-time
        - `knowledge_bases` ApiKnowledgeBase[]
          - `uuid` string
          - `name` string
          - `created_at` string, date-time
          - `updated_at` string, date-time
          - `tags` string[]
          - `region` string
          - `embedding_model_uuid` string
          - `project_id` string
          - `database_id` string
          - `last_indexing_job` ApiIndexingJob
            - `uuid` string
            - `knowledge_base_uuid` string
            - `data_source_uuids` string[]
            - `created_at` string, date-time
            - `updated_at` string, date-time
            - `started_at` string, date-time
            - `finished_at` string, date-time
            - `phase` 'BATCH_JOB_PHASE_UNKNOWN' | 'BATCH_JOB_PHASE_PENDING' | 'BATCH_JOB_PHASE_RUNNING' | 'BATCH_JOB_PHASE_SUCCEEDED' | 'BATCH_JOB_PHASE_FAILED' | 'BATCH_JOB_PHASE_ERROR' | 'BATCH_JOB_PHASE_CANCELLED'
            - `total_datasources` integer
            - `completed_datasources` integer
            - `tokens` integer
            - `status` 'INDEX_JOB_STATUS_UNKNOWN' | 'INDEX_JOB_STATUS_PARTIAL' | 'INDEX_JOB_STATUS_IN_PROGRESS' | 'INDEX_JOB_STATUS_COMPLETED' | 'INDEX_JOB_STATUS_FAILED' | 'INDEX_JOB_STATUS_NO_CHANGES' | 'INDEX_JOB_STATUS_PENDING'
          - `added_to_agent_at` string, date-time
          - `user_id` string, int64
          - `is_public` boolean
        - `instruction` string
        - `k` integer
        - `temperature` number, float
        - `top_p` number, float
        - `max_tokens` integer
        - `template_type` 'AGENT_TEMPLATE_TYPE_STANDARD' | 'AGENT_TEMPLATE_TYPE_ONE_CLICK'
        - `guardrails` ApiAgentTemplateGuardrail[]
          - `uuid` string
          - `priority` integer
        - `tags` string[]
        - `short_description` string
        - `long_description` string
        - `summary` string
      - `anthropic_api_key` ApiAnthropicAPIKeyInfo
        - `name` string
        - `uuid` string
        - `created_by` string, uint64
        - `created_at` string, date-time
        - `updated_at` string, date-time
        - `deleted_at` string, date-time
      - `openai_api_key` ApiOpenAIAPIKeyInfo
        - `name` string
        - `uuid` string
        - `created_by` string, uint64
        - `models` ApiModel[]
          - `uuid` string
          - `name` string
          - `inference_name` string
          - `version` ApiModelVersion
            - `major` integer
            - `minor` integer
            - `patch` integer
          - `inference_version` string
          - `url` string
          - `is_foundational` boolean
          - `upload_complete` boolean
          - `created_at` string, date-time
          - `updated_at` string, date-time
          - `metadata` object
          - `parent_uuid` string
          - `agreement` ApiAgreement
            - `uuid` string
            - `name` string
            - `description` string
            - `url` string
          - `provider` 'MODEL_PROVIDER_DIGITALOCEAN' | 'MODEL_PROVIDER_ANTHROPIC' | 'MODEL_PROVIDER_OPENAI'
          - `usecases` ApiModelUsecase[]
        - `created_at` string, date-time
        - `updated_at` string, date-time
        - `deleted_at` string, date-time
      - `retrieval_method` 'RETRIEVAL_METHOD_UNKNOWN' | 'RETRIEVAL_METHOD_REWRITE' | 'RETRIEVAL_METHOD_STEP_BACK' | 'RETRIEVAL_METHOD_SUB_QUERIES' | 'RETRIEVAL_METHOD_NONE'
      - `provide_citations` boolean
      - `workspace` ApiWorkspace — recursive
    - `evaluation_test_cases` ApiEvaluationTestCase[]
      - `test_case_uuid` string
      - `name` string
      - `description` string
      - `version` integer
      - `dataset_uuid` string
      - `dataset_name` string
      - `metrics` ApiEvaluationMetric[]
        - `metric_uuid` string
        - `metric_name` string
        - `description` string
        - `metric_type` 'METRIC_TYPE_UNSPECIFIED' | 'METRIC_TYPE_GENERAL_QUALITY' | 'METRIC_TYPE_RAG_AND_TOOL'
        - `metric_value_type` 'METRIC_VALUE_TYPE_UNSPECIFIED' | 'METRIC_VALUE_TYPE_NUMBER' | 'METRIC_VALUE_TYPE_STRING'
      - `star_metric` ApiStarMetric
        - `metric_uuid` string
        - `name` string
        - `success_threshold_pct` integer — The success threshold for the star metric. This is a percentage value between 0 and 100.
      - `total_runs` integer
      - `latest_version_number_of_runs` integer
      - `updated_by_user_id` string, uint64
      - `updated_by_user_email` string
      - `created_by_user_email` string
      - `created_by_user_id` string, uint64
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `archived_at` string, date-time

## Changes

- **2025-07-17** `5fc9af728e82` — 1 breaking, 8 warning, 9 info
  - request body became required
  - the optional response header `ratelimit-limit` removed for the status `200`
  - the optional response header `ratelimit-remaining` removed for the status `200`
  - the optional response header `ratelimit-reset` removed for the status `200`
  - …14 more
- **2025-07-17** `f8e8c290636c` — 1 warning, 14 info
  - added the new `METRIC_VALUE_TYPE_PERCENTAGE` enum value to the `workspace/evaluation_test_cases/items/metrics/items/metric_value_type` response property for the response status `200`
  - api operation id `create_workspace` removed and replaced with `genai_create_workspace`
  - the endpoint scheme security `bearer_auth` was added to the API
  - api tag `GradientAI Platform` added
  - …11 more
- **2025-06-25** `e8b3cbc80e18` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/digitalocean/apis/digitalocean-api/changes/v2/gen-ai/workspaces/post.md)

---

[API](https://skmtc.dev/digitalocean/apis/digitalocean-api.md) · [All operations](https://skmtc.dev/digitalocean/apis/digitalocean-api/llms.txt) · [OpenAPI document](https://skmtc.dev/digitalocean/apis/digitalocean-api/revisions/5fc9af728e82?raw)