PūnahaDocs
Pūnaha website

API

Create case types

Create case types. This applies the validated business action to the selected tenant or platform resource.

Applies to
Next (0.1 RC1 Preview)
Product revision
25748655d6be
Audience
Developers and integrators
Source reviewed
POST/api/case-types
Preview

Create case types. This applies the validated business action to the selected tenant or platform resource.

Operation ID postapiCaseTypes

Operation details

Purpose

Create case types. This applies the validated business action to the selected tenant or platform resource.

When to use it

Use this when the documented business action or resource creation is the intended next step.

When not to use it

Do not repeat the request blindly after an uncertain outcome. Read the resulting resource or background operation state first.

Contract

Availability

Product version
Next Product release
Licence
An active Product licence is required except for health, authentication, and licence remediation operations.
Entitlements
workflow.enabled
Service roles
workflow
Deployment
customer managed installation
Feature state
preview

Security

Access

Sign in: Use a session cookie or Bearer session token.

Actor
Authenticated Pūnaha actor authorised for the selected tenant and resource
Permission
cases.manage
Resource
case_type / create
Tenant rule
Tenant scoped unless the selected actor is performing an explicitly documented platform action. The x organization id header or authenticated session context selects the tenant. It does not grant access.
Explicit deny
An applicable explicit deny overrides an allow. Knowing or supplying a resource identifier never grants access.

Address, query and header fields

FieldLocationPresenceTypeMeaningLimits and example
x-request-idheaderOptionalstringOptional caller supplied correlation identifier. Pūnaha returns the effective value in the response header.Minimum length: 1. Maximum length: 200. Example: example request 001

Request body

Content type: application/json. Presence: Required.

Operation request. Every property documents omission, null, sensitivity, source, mutability, availability, access, and lifecycle semantics through JSON Schema and x punaha-* annotations.

Request fields4 documented fields

Request fields

FieldPresenceTypeMeaningEmpty and defaultLimits and exampleAccess, sensitivity and lifecycle
definitionoptionalCaseworkDefinitionRequest or nullThe definition associated with this resource or operation.The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.No additional schema limit is listedInherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
descriptionrequiredstringThe description associated with this resource or operation.The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.Example: example valueInherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
displayNamerequiredstringThe display name associated with this resource or operation.The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.Example: example valueInherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
slugrequiredstringThe slug associated with this resource or operation.The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.Example: example valueInherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
Complete representative request using synthetic data
{
  "definition": {
    "artifacts": [
      {
        "direction": "example-value",
        "id": "example-value",
        "sourceRef": "example-value",
        "targetRef": "example-value",
        "text": "example-value",
        "textFormat": "example-value",
        "type": "example-value"
      }
    ],
    "caseFile": [
      {
        "definitionRef": "example-value",
        "definitionType": "example-value",
        "id": "example-value",
        "multiplicity": "example-value",
        "name": "example-value",
        "parentId": "example-value",
        "properties": [
          {
            "id": "example-value",
            "name": "example-value",
            "type": "example-value"
          }
        ],
        "sourceRef": "example-value",
        "structureRef": "example-value",
        "targetRefs": [
          "example-value"
        ]
      }
    ],
    "diagram": {
      "edges": [
        {
          "elementRef": "example-value",
          "id": "example-value",
          "sourceRef": "example-value",
          "standardEventVisible": true,
          "targetRef": "example-value",
          "waypoints": [
            {
              "x": 1.5,
              "y": 1.5
            }
          ]
        }
      ],
      "height": 1.5,
      "id": "example-value",
      "name": "example-value",
      "shapes": [
        {
          "collapsed": true,
          "elementRef": "example-value",
          "height": 1.5,
          "id": "example-value",
          "planningTableCollapsed": true,
          "width": 1.5,
          "x": 1.5,
          "y": 1.5
        }
      ],
      "width": 1.5
    },
    "fields": [
      {
        "description": "example-value",
        "id": "example-value",
        "label": "example-value",
        "maximum": 1.5,
        "minimum": 1.5,
        "options": [
          "example-value"
        ],
        "requiredAtStart": true,
        "sensitive": true,
        "type": "example-value"
      }
    ],
    "format": "example-value",
    "outcomes": [
      "example-value"
    ],
    "policies": {
      "allowReopen": true,
      "classification": "example-value",
      "completionMode": "example-value",
      "retentionDays": 1
    },
    "purpose": "example-value",
    "requirements": [
      {
        "appliesWhen": {
          "expressionLanguage": "example-value",
          "operator": "example-value",
          "source": "example-value",
          "value": "example-value"
        },
        "blocksCompletion": true,
        "description": "example-value",
        "due": {
          "amount": 1,
          "from": "example-value",
          "unit": "example-value"
        },
        "enforcement": "example-value",
        "fieldId": "example-value",
        "id": "example-value",
        "milestoneId": "example-value",
        "name": "example-value",
        "planItemId": "example-value",
        "responsibleRole": "example-value",
        "stageId": "example-value",
        "type": "example-value",
        "waivable": true,
        "waiverRole": "example-value"
      }
    ],
    "roles": [
      {
        "description": "example-value",
        "id": "example-value",
        "name": "example-value"
      }
    ],
    "schemaVersion": 1,
    "sentries": [
      {
        "id": "example-value",
        "ifPart": [
          {
            "expressionLanguage": "example-value",
            "operator": "example-value",
            "source": "example-value",
            "value": "example-value"
          }
        ],
        "name": "example-value",
        "onParts": [
          {
            "exitCriterionRef": "example-value",
            "id": "example-value",
            "sourceRef": "example-value",
            "sourceType": "example-value",
            "standardEvent": "example-value"
          }
        ]
      }
    ],
    "stages": [
      {
        "autoComplete": true,
        "control": {
          "manualActivation": {
            "condition": [
              {
                "expressionLanguage": "example-value",
                "operator": "example-value",
                "source": "example-value",
                "value": "example-value"
              }
            ],
            "sentryRef": "example-value"
          },
          "repetition": {
            "condition": [
              {
                "expressionLanguage": "example-value",
                "operator": "example-value",
                "source": "example-value",
                "value": "example-value"
              }
            ],
            "sentryRef": "example-value"
          },
          "required": {
            "condition": [
              {
                "expressionLanguage": "example-value",
                "operator": "example-value",
                "source": "example-value",
                "value": "example-value"
              }
            ],
            "sentryRef": "example-value"
          }
        },
        "description": "example-value",
        "entryCriteria": [
          {
            "expressionLanguage": "example-value",
            "operator": "example-value",
            "source": "example-value",
            "value": "example-value"
          }
        ],
        "entrySentryRefs": [
          "example-value"
        ],
        "exitCriteria": [
          {
            "expressionLanguage": "example-value",
            "operator": "example-value",
            "source": "example-value",
            "value": "example-value"
          }
        ],
        "exitSentryRefs": [
          "example-value"
        ],
        "id": "example-value",
        "items": [
          {
            "authorizedRoles": [
              "example-value"
            ],
            "blocking": true,
            "caseTypeId": "example-value",
            "caseTypeVersion": 1,
            "children": [
              {}
            ],
            "control": {
              "manualActivation": {
                "condition": [
                  {
                    "expressionLanguage": "example-value",
                    "operator": "example-value",
                    "source": "example-value",
                    "value": "example-value"
                  }
                ],
                "sentryRef": "example-value"
              },
              "repetition": {
                "condition": [
                  {
                    "expressionLanguage": "example-value",
                    "operator": "example-value",
                    "source": "example-value",
                    "value": "example-value"
                  }
                ],
                "sentryRef": "example-value"
              },
              "required": {
                "condition": [
                  {
                    "expressionLanguage": "example-value",
                    "operator": "example-value",
                    "source": "example-value",
                    "value": "example-value"
                  }
                ],
                "sentryRef": "example-value"
              }
            },
            "correlationField": "example-value",
            "decision": {
              "hitPolicy": "example-value",
              "id": "example-value",
              "inputs": [
                {
                  "id": "example-value",
                  "label": "example-value"
                }
              ],
              "name": "example-value",
              "outputs": [
                {
                  "id": "example-value",
                  "label": "example-value"
                }
              ],
              "rules": [
                {
                  "conditions": {},
                  "id": "example-value",
                  "outputs": {}
                }
              ]
            },
            "definitionRef": "example-value",
            "description": "example-value",
            "due": {
              "amount": 1,
              "from": "example-value",
              "unit": "example-value"
            },
            "entryCriteria": [
              {
                "expressionLanguage": "example-value",
                "operator": "example-value",
                "source": "example-value",
                "value": "example-value"
              }
            ],
            "entrySentryRefs": [
              "example-value"
            ],
            "eventType": "example-value",
            "exitCriteria": [
              {
                "expressionLanguage": "example-value",
                "operator": "example-value",
                "source": "example-value",
                "value": "example-value"
              }
            ],
            "exitSentryRefs": [
              "example-value"
            ],
            "externalImportType": "example-value",
            "externalLocation": "example-value",
            "externalNamespace": "example-value",
            "externalPrefix": "example-value",
            "externalRef": "example-value",
            "id": "example-value",
            "implementationType": "example-value",
            "input": {},
            "inputMappings": [
              {
                "id": "example-value",
                "source": "example-value",
                "target": "example-value",
                "transformation": "example-value"
              }
            ],
            "manualActivation": true,
            "name": "example-value",
            "outputMappings": [
              {
                "id": "example-value",
                "source": "example-value",
                "target": "example-value",
                "transformation": "example-value"
              }
            ],
            "planningTable": {
              "applicabilityRules": [
                {
                  "expressionLanguage": "example-value",
                  "operator": "example-value",
                  "source": "example-value",
                  "value": "example-value"
                }
              ],
              "authorizedRoles": [
                "example-value"
              ],
              "id": "example-value",
              "itemRefs": [
                "example-value"
              ],
              "name": "example-value",
              "tables": [
                {}
              ]
            },
            "repeatable": true,
            "required": true,
            "roleId": "example-value",
            "timeoutMinutes": 1,
            "timerExpression": "example-value",
            "timerStart": {
              "exitCriterionRef": "example-value",
              "id": "example-value",
              "sourceRef": "example-value",
              "sourceType": "example-value",
              "standardEvent": "example-value"
            },
            "type": "example-value",
            "workflowId": "example-value",
            "workflowVersion": 1
          }
        ],
        "manualActivation": true,
        "name": "example-value",
        "parentId": "example-value",
        "planningTable": {
          "applicabilityRules": [
            {
              "expressionLanguage": "example-value",
              "operator": "example-value",
              "source": "example-value",
              "value": "example-value"
            }
          ],
          "authorizedRoles": [
            "example-value"
          ],
          "id": "example-value",
          "itemRefs": [
            "example-value"
          ],
          "name": "example-value",
          "tables": [
            {}
          ]
        },
        "repeatable": true,
        "required": true
      }
    ]
  },
  "description": "example-value",
  "displayName": "example-value",
  "slug": "example-value"
}
Smallest schema valid request
{
  "description": "example-value",
  "displayName": "example-value",
  "slug": "example-value"
}

Responses

StatusMeaning and correction boundaryBody
201The resource was created and the response contains its current representation.application/json, object
400The operation failed with HTTP 400. Inspect error.code and error.details, apply the documented correction, and retain x request id.application/json, APIError
401The operation failed with HTTP 401. Inspect error.code and error.details, apply the documented correction, and retain x request id.application/json, APIError
402The operation failed with HTTP 402. Inspect error.code and error.details, apply the documented correction, and retain x request id.application/json, APIError
403The operation failed with HTTP 403. Inspect error.code and error.details, apply the documented correction, and retain x request id.application/json, APIError
409The operation failed with HTTP 409. Inspect error.code and error.details, apply the documented correction, and retain x request id.application/json, APIError
423The operation failed with HTTP 423. Inspect error.code and error.details, apply the documented correction, and retain x request id.application/json, APIError
500The operation failed with HTTP 500. Inspect error.code and error.details, apply the documented correction, and retain x request id.application/json, APIError
503The operation failed with HTTP 503. Inspect error.code and error.details, apply the documented correction, and retain x request id.application/json, APIError
201 response fields1 documented field

201 response fields

FieldPresenceTypeMeaningEmpty and defaultLimits and exampleAccess, sensitivity and lifecycle
datarequiredJSON valueA JSON compatible value returned by this operation.The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.Example: example valueInherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
Successful response using synthetic data
{
  "data": "example-value"
}

Effects

Behaviour and other effects

Changes
Validates access and input, then applies the operation specific state change. A failed validation or authorisation check does not intentionally apply the requested change.
Audit events
case_type.created
Background work
No background work is inferred. The success response represents completion of the HTTP action.
External effects
No external call is inferred from the route name. Operation specific service behaviour remains authoritative.
Transaction boundary
The HTTP success or error describes the synchronous boundary. Background operations have their own observable lifecycle and may outlive the request.

Operation

Reliability

Idempotent
No
Retry
Do not retry automatically after a timeout or lost response. Read current state first.
Concurrency
Use documented If Match or resource revision fields where exposed. Otherwise read current state before changing it and handle HTTP 409 conflicts.
Consistency
The response reflects the synchronous operation boundary. Background and provider backed state can converge later and must be read through its status operation.
Timeout
Client timeouts do not cancel completed or already started server work unless the operation explicitly supports cancellation.
Request ID
Send or record x request id and retain the returned value for diagnosis.

Errors and corrections

StatusCodeCauseCorrectionRetryablePartial work
400INVALID_REQUEST_BODYThe request body or supplied field values are invalid.Correct the named field or rule in error.details, then submit a new request. Retrying an unchanged request will not help.No unchanged retryNo requested mutation is expected before this failure boundary.
401AUTHENTICATION_REQUIREDA valid authenticated session or supported token is required.Authenticate again using a supported mechanism and confirm that the credential is current.No unchanged retryNo requested mutation is expected before this failure boundary.
402FEATURE_NOT_LICENSEDThe active licence does not include a required entitlement.Use an operation covered by the active entitlement or ask the System Owner to review the signed licence.No unchanged retryNo requested mutation is expected before this failure boundary.
403PERMISSION_REQUIREDThe authenticated actor does not have the exact permission or resource action.Select the correct tenant and resource, then ask an authorised administrator to grant the exact documented action if appropriate.No unchanged retryNo requested mutation is expected before this failure boundary.
409STATE_CONFLICTCurrent resource state or a dependency prevents the requested change.Read current state, resolve the named dependency or lifecycle conflict, and submit a deliberate new request.No unchanged retryThe caller must read current resource or background operation state before retrying because work may have started before the failure became observable.
423LICENCE_REMEDIATION_REQUIREDThe installation is restricted and permits only licence remediation actions.Complete the indicated licence or membership remediation before retrying Product work.No unchanged retryThe caller must read current resource or background operation state before retrying because work may have started before the failure became observable.
500INTERNAL_ERRORPūnaha could not complete the operation because of an unexpected internal failure.Retain x request id and the stable error code, avoid blind retries, and investigate the operation or contact support. Code: INTERNAL_ERROR.No unchanged retryThe caller must read current resource or background operation state before retrying because work may have started before the failure became observable.
503DEPENDENCY_UNAVAILABLEA required node, database, provider, or service is temporarily unavailable.Retain x request id, check health and the named dependency, then retry with bounded backoff when safe.Yes, with the documented safeguardsThe caller must read current resource or background operation state before retrying because work may have started before the failure became observable.

Code examples

Use a supported credential and synthetic data. Do not disable TLS checks or retry a request that changes state blindly.

cURL example
curl --request POST "$PUNAHA_URL/api/case-types" \
  --header "Authorization: Bearer $PUNAHA_TOKEN" \
  --header "x-request-id: example-request-001" \
  --header "Content-Type: application/json" \
  --data '{"definition":{"artifacts":[{"direction":"example-value","id":"example-value","sourceRef":"example-value","targetRef":"example-value","text":"example-value","textFormat":"example-value","type":"example-value"}],"caseFile":[{"definitionRef":"example-value","definitionType":"example-value","id":"example-value","multiplicity":"example-value","name":"example-value","parentId":"example-value","properties":[{"id":"example-value","name":"example-value","type":"example-value"}],"sourceRef":"example-value","structureRef":"example-value","targetRefs":["example-value"]}],"diagram":{"edges":[{"elementRef":"example-value","id":"example-value","sourceRef":"example-value","standardEventVisible":true,"targetRef":"example-value","waypoints":[{"x":1.5,"y":1.5}]}],"height":1.5,"id":"example-value","name":"example-value","shapes":[{"collapsed":true,"elementRef":"example-value","height":1.5,"id":"example-value","planningTableCollapsed":true,"width":1.5,"x":1.5,"y":1.5}],"width":1.5},"fields":[{"description":"example-value","id":"example-value","label":"example-value","maximum":1.5,"minimum":1.5,"options":["example-value"],"requiredAtStart":true,"sensitive":true,"type":"example-value"}],"format":"example-value","outcomes":["example-value"],"policies":{"allowReopen":true,"classification":"example-value","completionMode":"example-value","retentionDays":1},"purpose":"example-value","requirements":[{"appliesWhen":{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"},"blocksCompletion":true,"description":"example-value","due":{"amount":1,"from":"example-value","unit":"example-value"},"enforcement":"example-value","fieldId":"example-value","id":"example-value","milestoneId":"example-value","name":"example-value","planItemId":"example-value","responsibleRole":"example-value","stageId":"example-value","type":"example-value","waivable":true,"waiverRole":"example-value"}],"roles":[{"description":"example-value","id":"example-value","name":"example-value"}],"schemaVersion":1,"sentries":[{"id":"example-value","ifPart":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"name":"example-value","onParts":[{"exitCriterionRef":"example-value","id":"example-value","sourceRef":"example-value","sourceType":"example-value","standardEvent":"example-value"}]}],"stages":[{"autoComplete":true,"control":{"manualActivation":{"condition":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"sentryRef":"example-value"},"repetition":{"condition":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"sentryRef":"example-value"},"required":{"condition":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"sentryRef":"example-value"}},"description":"example-value","entryCriteria":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"entrySentryRefs":["example-value"],"exitCriteria":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"exitSentryRefs":["example-value"],"id":"example-value","items":[{"authorizedRoles":["example-value"],"blocking":true,"caseTypeId":"example-value","caseTypeVersion":1,"children":[{}],"control":{"manualActivation":{"condition":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"sentryRef":"example-value"},"repetition":{"condition":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"sentryRef":"example-value"},"required":{"condition":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"sentryRef":"example-value"}},"correlationField":"example-value","decision":{"hitPolicy":"example-value","id":"example-value","inputs":[{"id":"example-value","label":"example-value"}],"name":"example-value","outputs":[{"id":"example-value","label":"example-value"}],"rules":[{"conditions":{},"id":"example-value","outputs":{}}]},"definitionRef":"example-value","description":"example-value","due":{"amount":1,"from":"example-value","unit":"example-value"},"entryCriteria":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"entrySentryRefs":["example-value"],"eventType":"example-value","exitCriteria":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"exitSentryRefs":["example-value"],"externalImportType":"example-value","externalLocation":"example-value","externalNamespace":"example-value","externalPrefix":"example-value","externalRef":"example-value","id":"example-value","implementationType":"example-value","input":{},"inputMappings":[{"id":"example-value","source":"example-value","target":"example-value","transformation":"example-value"}],"manualActivation":true,"name":"example-value","outputMappings":[{"id":"example-value","source":"example-value","target":"example-value","transformation":"example-value"}],"planningTable":{"applicabilityRules":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"authorizedRoles":["example-value"],"id":"example-value","itemRefs":["example-value"],"name":"example-value","tables":[{}]},"repeatable":true,"required":true,"roleId":"example-value","timeoutMinutes":1,"timerExpression":"example-value","timerStart":{"exitCriterionRef":"example-value","id":"example-value","sourceRef":"example-value","sourceType":"example-value","standardEvent":"example-value"},"type":"example-value","workflowId":"example-value","workflowVersion":1}],"manualActivation":true,"name":"example-value","parentId":"example-value","planningTable":{"applicabilityRules":[{"expressionLanguage":"example-value","operator":"example-value","source":"example-value","value":"example-value"}],"authorizedRoles":["example-value"],"id":"example-value","itemRefs":["example-value"],"name":"example-value","tables":[{}]},"repeatable":true,"required":true}]},"description":"example-value","displayName":"example-value","slug":"example-value"}'

Version history

  • Next Product release: Operation documented from the current registered Go route and handler contract.

Pūnaha Docs

Search the guides

Enter at least two characters.

    Product screen

    View the full screenshot