REST reference · v1

Create a task

POST/v1/workspaces/{workspaceId}/tasks

Portal admin/operator. Explicit assigneeEmail additionally requires the designated access administrator and an eligible active portal member. Saves requested work; no external execution.

Company permissions

Portal admin/operator. Explicit assigneeEmail additionally requires the designated access administrator and an eligible active portal member. Saves requested work; no external execution.

Required OAuth scopes: orchesphere.read, orchesphere.jobs. How scopes and company rights work.

Path and header parameters

Name	Location	Required	Allowed values / bounds
`workspaceId`	path	Yes	`string` minLength: 8 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]{8,80}$

Request

JSON body: required.

Field	Type	Required	Description / bounds
`portalId`	`string`	Yes	minLength: 8 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]{8,80}$
`title`	`string`	Yes	minLength: 2 · maxLength: 240
`description`	`string`	No	maxLength: 6000
`assigneeEmail`	`string`	No	minLength: 3 · maxLength: 254 · format: email

Complete request schema

{
  "type": "object",
  "properties": {
    "portalId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,80}$",
      "minLength": 8,
      "maxLength": 80
    },
    "title": {
      "type": "string",
      "minLength": 2,
      "maxLength": 240
    },
    "description": {
      "type": "string",
      "maxLength": 6000
    },
    "assigneeEmail": {
      "type": "string",
      "format": "email",
      "minLength": 3,
      "maxLength": 254
    }
  },
  "required": [
    "portalId",
    "title"
  ],
  "additionalProperties": false
}

http

POST /v1/workspaces/{workspaceId}/tasks HTTP/1.1
Host: api.orchesphere.ai
Authorization: Bearer <access_token>
Accept: application/json
Content-Type: application/json

{
  "portalId": "22222222-2222-4222-8222-222222222222",
  "title": "Review the saved verification",
  "description": "Requested work only."
}

Use actual IDs returned for your assigned workspace. The example values are fictional. REST v1 accepts no query parameters.

Response · 201

Field	Type	Required	Description / bounds
`ok`	`object`	Yes	—
`workspaceId`	`string`	Yes	minLength: 8 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]{8,80}$
`task`	`object`	Yes	—

Complete response schema

{
  "type": "object",
  "properties": {
    "ok": {
      "const": true
    },
    "workspaceId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,80}$",
      "minLength": 8,
      "maxLength": 80
    },
    "task": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{8,80}$",
          "minLength": 8,
          "maxLength": 80
        },
        "workspaceId": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{8,80}$",
          "minLength": 8,
          "maxLength": 80
        },
        "portalId": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{8,80}$",
          "minLength": 8,
          "maxLength": 80
        },
        "title": {
          "type": "string",
          "minLength": 2,
          "maxLength": 240
        },
        "description": {
          "type": "string",
          "maxLength": 6000
        },
        "status": {
          "type": "string",
          "enum": [
            "todo",
            "in_progress",
            "blocked",
            "review",
            "done",
            "cancelled"
          ]
        },
        "assigneeEmail": {
          "anyOf": [
            {
              "type": "string",
              "format": "email"
            },
            {
              "type": "null"
            }
          ]
        },
        "createdBy": {
          "type": "string"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "role": {
          "type": "string",
          "enum": [
            "admin",
            "contributor",
            "reviewer",
            "viewer"
          ]
        },
        "canEdit": {
          "type": "boolean"
        },
        "canManage": {
          "type": "boolean"
        }
      },
      "required": [
        "id",
        "workspaceId",
        "portalId",
        "title",
        "description",
        "status",
        "assigneeEmail",
        "createdBy",
        "createdAt",
        "updatedAt",
        "role",
        "canEdit",
        "canManage"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "ok",
    "workspaceId",
    "task"
  ],
  "additionalProperties": false
}

json

{
  "ok": true,
  "workspaceId": "11111111-1111-4111-8111-111111111111",
  "task": {
    "id": "33333333-3333-4333-8333-333333333333",
    "workspaceId": "11111111-1111-4111-8111-111111111111",
    "portalId": "22222222-2222-4222-8222-222222222222",
    "title": "Review the saved verification",
    "description": "Requested work only.",
    "status": "todo",
    "assigneeEmail": null,
    "createdBy": "developer@example.com",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "role": "contributor",
    "canEdit": true,
    "canManage": false
  }
}

Errors

Status	Meaning
`400`	Invalid path/query/body/header or business validation.
`401`	Missing, expired, revoked, invalid or wrong-resource token.
`402`	Verified company payment is required.
`403`	Insufficient token scope or current company/service/portal/task authority.
`404`	Unknown endpoint or record not found/inaccessible.
`405`	Method is not supported for this path.
`409`	State, quota or idempotency conflict; re-read current state.
`413`	Request exceeds 24,000 bytes.
`415`	Use uncompressed application/json.
`429`	Company job/rate/paid-period allowance reached.
`503`	Temporarily unavailable; a lost mutation response does not prove nothing was saved.

Request limits and recovery · All REST operations