Apps API

The Apps API provides endpoints for managing Cogniscript applications and their execution processes.

Base URL: /apps and /namespaces/{namespaceName}/apps

Authentication: Bearer Token or API Key

Endpoints

Method	Endpoint	Description
GET	`/apps`	List all apps in tenant
GET	`/namespaces/{namespaceName}/apps`	List apps in namespace
POST	`/namespaces/{namespaceName}/apps`	Create a new app
GET	`/apps/by-id/{id}`	Get app by ID
GET	`/namespaces/{namespaceName}/apps/by-name/{name}`	Get app by name
PUT	`/apps/by-id/{id}/versions/{versionNumber}/start`	Start app version
PUT	`/namespaces/{namespaceName}/apps/by-name/{name}/versions/latest/start`	Start latest version
GET	`/apps/processes/by-id/{id}`	Get process by ID
PUT	`/apps/processes/by-id/{id}/inputs`	Update process inputs
GET	`/namespaces/{namespaceName}/apps/processes`	List running processes

List All Apps

Returns all apps across the tenant.

GET /apps

Roles: Tenant.Admin, Tenant.User

Response

Returns an array of App objects.

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "userCreatedById": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "namespaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "dateCreated": "2026-01-05T10:30:00Z",
    "dateUpdated": "2026-01-05T10:30:00Z",
    "name": "my-app",
    "versions": []
  }
]

List Apps in Namespace

Returns all apps within a specific namespace.

GET /namespaces/{namespaceName}/apps

Roles: Tenant.Admin, Tenant.User

Path Parameters

Parameter	Type	Required	Description
`namespaceName`	string	Yes	The namespace identifier

Response

Returns an array of App objects.

Create App

Creates a new application in a namespace.

POST /namespaces/{namespaceName}/apps

Roles: Tenant.Admin, Tenant.User

Path Parameters

Parameter	Type	Required	Description
`namespaceName`	string	Yes	The namespace identifier

Request Body: AppCreateRequest

{
  "name": "my-new-app"
}

Response

Returns the created App object.

Example

Request:

curl -X POST "https://api.maitento.com/namespaces/production/apps" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "order-processor"}'

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenantId": "t1234567-89ab-cdef-0123-456789abcdef",
  "userCreatedById": "u1234567-89ab-cdef-0123-456789abcdef",
  "namespaceId": "n1234567-89ab-cdef-0123-456789abcdef",
  "dateCreated": "2026-01-05T14:30:00Z",
  "dateUpdated": "2026-01-05T14:30:00Z",
  "name": "order-processor",
  "versions": []
}

Errors

Status	Error	Description
400	Validation error	Name exceeds 150 characters or is empty
400	Duplicate name	App with this name already exists in namespace
404	Not found	Namespace does not exist

Get App by ID

Retrieves a specific app by its unique identifier.

GET /apps/by-id/{id}

Roles: Tenant.Admin, Tenant.User

Path Parameters

Parameter	Type	Required	Description
`id`	Guid	Yes	The app’s unique identifier

Response

Returns an App object.

Errors

Status	Error	Description
404	Not found	App with specified ID does not exist

Get App by Name

Retrieves a specific app by namespace and name.

GET /namespaces/{namespaceName}/apps/by-name/{name}

Roles: Tenant.Admin, Tenant.User

Path Parameters

Parameter	Type	Required	Description
`namespaceName`	string	Yes	The namespace identifier
`name`	string	Yes	The app name

Response

Returns an App object.

Start App Version

Starts a specific version of an app, creating a new process.

PUT /apps/by-id/{id}/versions/{versionNumber}/start

Roles: Tenant.Admin, Tenant.User

Path Parameters

Parameter	Type	Required	Description
`id`	Guid	Yes	The app’s unique identifier
`versionNumber`	int	Yes	The version number to start (minimum: 1)

Request Body: AppStartRequest

{
  "inputs": [
    {
      "name": "apiKey",
      "value": "sk-abc123"
    },
    {
      "name": "maxItems",
      "value": "100"
    }
  ]
}

Response

Returns an AppProcess object.

Example

Request:

curl -X PUT "https://api.maitento.com/apps/by-id/a1b2c3d4.../versions/1/start" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {"name": "customerId", "value": "cust-12345"},
      {"name": "debug", "value": "false"}
    ]
  }'

Response:

{
  "id": "p1234567-89ab-cdef-0123-456789abcdef",
  "tenantId": "t1234567-89ab-cdef-0123-456789abcdef",
  "userCreatedById": "u1234567-89ab-cdef-0123-456789abcdef",
  "dateCreated": "2026-01-05T14:35:00Z",
  "dateUpdated": "2026-01-05T14:35:00Z",
  "app": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "version": 1
  },
  "dateStarted": null,
  "dateEnded": null,
  "executionTime": "00:00:00",
  "inputs": [
    {"name": "customerId", "value": "cust-12345"},
    {"name": "debug", "value": "false"}
  ],
  "outputs": [],
  "consoleOutputs": [],
  "failureDetails": null,
  "status": "New",
  "pauseType": "None",
  "pauseAssociatedId": null,
  "returnValue": null
}

Errors

Status	Error	Description
400	Missing inputs	Required input parameters not provided
400	Invalid input	Input name doesn’t match app definition
400	Version disabled	The specified version is disabled
404	Not found	App or version does not exist

Start App Latest Version

Starts the latest active version of an app by name.

PUT /namespaces/{namespaceName}/apps/by-name/{name}/versions/latest/start

Roles: Tenant.Admin, Tenant.User

Path Parameters

Parameter	Type	Required	Description
`namespaceName`	string	Yes	The namespace identifier
`name`	string	Yes	The app name

Request Body

Same as AppStartRequest.

Response

Returns an AppProcess object.

Get Process

Retrieves details of a specific app process.

GET /apps/processes/by-id/{id}

Roles: Tenant.Admin, Tenant.User

Path Parameters

Parameter	Type	Required	Description
`id`	Guid	Yes	The process unique identifier

Response

Returns an AppProcess object.

Update Process Inputs

Updates input values for a running or paused process.

PUT /apps/processes/by-id/{id}/inputs

Roles: Tenant.Admin, Tenant.User

Path Parameters

Parameter	Type	Required	Description
`id`	Guid	Yes	The process unique identifier

Request Body

Same as AppStartRequest.

Response

Returns the updated AppProcess object.

Errors

Status	Error	Description
400	Process completed	Cannot update inputs for finished/errored/killed process
400	Invalid input	Input name doesn’t match app definition
404	Not found	Process does not exist

List Running Processes

Returns all active processes in a namespace.

GET /namespaces/{namespaceName}/apps/processes

Roles: Tenant.Admin, Tenant.User

Path Parameters

Parameter	Type	Required	Description
`namespaceName`	string	Yes	The namespace identifier

Response

Returns an array of AppProcessWithDetails objects.

[
  {
    "id": "p1234567-89ab-cdef-0123-456789abcdef",
    "namespaceName": "production",
    "appName": "order-processor",
    "status": "Running",
    "dateStarted": "2026-01-05T14:35:00Z"
  }
]

Data Types

AppCreateRequest

Request body for creating a new app.

Field	Type	Required	Validation
`name`	string	Yes	Max 150 chars, non-empty

Example:

{
  "name": "order-processor"
}

AppStartRequest

Request body for starting an app or updating process inputs.

Field	Type	Required	Description
`inputs`	NameValuePair[]	Yes	Input parameters

Example:

{
  "inputs": [
    {"name": "customerId", "value": "cust-123"},
    {"name": "maxItems", "value": "50"}
  ]
}

App

Represents a Cogniscript application.

Field	Type	Description
`id`	Guid	Unique identifier
`tenantId`	Guid	Owning tenant ID
`userCreatedById`	Guid	Creator’s user ID
`namespaceId`	Guid	Containing namespace ID
`dateCreated`	DateTime	Creation timestamp (UTC)
`dateUpdated`	DateTime	Last update timestamp (UTC)
`name`	string	Application name
`versions`	AppVersion[]	Deployed versions

Example:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenantId": "t1234567-89ab-cdef-0123-456789abcdef",
  "userCreatedById": "u1234567-89ab-cdef-0123-456789abcdef",
  "namespaceId": "n1234567-89ab-cdef-0123-456789abcdef",
  "dateCreated": "2026-01-05T14:30:00Z",
  "dateUpdated": "2026-01-05T14:30:00Z",
  "name": "order-processor",
  "versions": [
    {
      "version": 1,
      "date": "2026-01-05T14:30:00Z",
      "isDisabled": false,
      "inputs": [],
      "executionTimeLimit": "00:05:00"
    }
  ]
}

AppVersion

A specific version of an application.

Field	Type	Description
`version`	int	Version number (starts at 1)
`date`	DateTime	Version creation timestamp
`isDisabled`	bool	Whether version is disabled
`inputs`	AppInput[]	Defined input parameters
`externalOperationsMcp`	object[]	MCP connector bindings
`externalOperationsOpenApi`	object[]	OpenAPI connector bindings
`fileChecksum`	string	Hash of compiled app file
`executionTimeLimit`	TimeSpan?	Max execution time

Example:

{
  "version": 1,
  "date": "2026-01-05T14:30:00Z",
  "isDisabled": false,
  "inputs": [
    {"name": "customerId", "dataType": "String"},
    {"name": "maxItems", "dataType": "Integer"}
  ],
  "externalOperationsMcp": [],
  "externalOperationsOpenApi": [],
  "fileChecksum": "d7a8fbb307d7809469ca9...",
  "executionTimeLimit": "00:05:00"
}

AppInput

Defines an input parameter for an app version.

Field	Type	Description
`name`	string	Input parameter name
`dataType`	AppDataType	Data type of the input

Example:

{
  "name": "customerId",
  "dataType": "String"
}

AppProcess

Represents a running or completed app execution.

Field	Type	Description
`id`	Guid	Unique process identifier
`tenantId`	Guid	Owning tenant ID
`userCreatedById`	Guid	User who started the process
`dateCreated`	DateTime	Process creation timestamp
`dateUpdated`	DateTime	Last update timestamp
`app`	VersionReference	Reference to app and version
`dateStarted`	DateTime?	When execution began
`datePaused`	DateTime?	When process was paused
`dateEnded`	DateTime?	When execution completed
`executionTime`	TimeSpan	Total execution duration
`inputs`	NameValuePair[]	Input parameter values
`outputs`	AppOutput[]	Output values produced
`consoleOutputs`	AppConsoleOutput[]	Console log entries
`failureDetails`	string?	Error message if failed
`status`	AppProcessStatus	Current process status
`pauseType`	AppProcessPauseType	Type of pause (if paused)
`pauseAssociatedId`	Guid?	Related entity ID when paused
`returnValue`	string?	Final return value
`hostname`	string?	Execution node hostname

Example:

{
  "id": "p1234567-89ab-cdef-0123-456789abcdef",
  "tenantId": "t1234567-89ab-cdef-0123-456789abcdef",
  "userCreatedById": "u1234567-89ab-cdef-0123-456789abcdef",
  "dateCreated": "2026-01-05T14:35:00Z",
  "dateUpdated": "2026-01-05T14:36:00Z",
  "app": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "version": 1
  },
  "dateStarted": "2026-01-05T14:35:01Z",
  "datePaused": null,
  "dateEnded": "2026-01-05T14:36:00Z",
  "executionTime": "00:00:59",
  "inputs": [
    {"name": "customerId", "value": "cust-123"}
  ],
  "outputs": [
    {
      "name": "result",
      "type": "JsonObject",
      "value": "{\"processed\": true}",
      "date": "2026-01-05T14:36:00Z"
    }
  ],
  "consoleOutputs": [
    {
      "text": "Processing customer cust-123",
      "type": "Normal",
      "date": "2026-01-05T14:35:02Z"
    }
  ],
  "failureDetails": null,
  "status": "Finished",
  "pauseType": "None",
  "pauseAssociatedId": null,
  "returnValue": "success",
  "hostname": "runner-01"
}

AppProcessWithDetails

Extends AppProcess with namespace and app names.

Field	Type	Description
(all AppProcess fields)
`namespaceName`	string	Namespace identifier
`appName`	string	Application name

Example:

{
  "id": "p1234567-89ab-cdef-0123-456789abcdef",
  "namespaceName": "production",
  "appName": "order-processor",
  "status": "Running",
  "dateStarted": "2026-01-05T14:35:01Z"
}

AppOutput

An output value produced by an app process.

Field	Type	Description
`name`	string	Output parameter name
`type`	AppDataType	Data type of the output
`value`	string?	Output value
`date`	DateTime	When output was recorded

Example:

{
  "name": "orderCount",
  "type": "Integer",
  "value": "42",
  "date": "2026-01-05T14:36:00Z"
}

AppConsoleOutput

A console log entry from an app process.

Field	Type	Description
`text`	string	Console output text
`type`	AppConsoleOutputType	Output type
`date`	DateTime	Timestamp

Example:

{
  "text": "Processing order #12345",
  "type": "Normal",
  "date": "2026-01-05T14:35:30Z"
}

VersionReference

Reference to a specific app version.

Field	Type	Required	Description
`id`	Guid	Yes	App ID
`version`	int	Yes	Version number (min: 1)

Example:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 1
}

NameValuePair

A key-value pair for inputs and other parameters.

Field	Type	Required	Description
`name`	string	Yes	Parameter name (min 1 char)
`value`	string	Yes	Parameter value

Example:

{
  "name": "customerId",
  "value": "cust-12345"
}

Enumerations

AppDataType

Value	Description
`String`	Text value
`Integer`	Whole number
`Decimal`	Decimal number
`Guid`	Unique identifier
`Bool`	Boolean (true/false)
`Date`	Date/time value
`JsonObject`	JSON object
`JsonArray`	JSON array

AppProcessStatus

Value	Description
`New`	Process created, not yet started
`Running`	Currently executing
`HumanInteractionRequired`	Waiting for user input
`WaitingToResume`	Queued to resume
`Paused`	Execution suspended
`Finished`	Completed successfully
`Error`	Failed with error
`Killed`	Terminated/cancelled

AppProcessPauseType

Value	Description
`None`	Not paused
`App`	Paused by app logic
`Interaction`	Paused for human interaction
`CodeGeneration`	Paused for code generation

AppConsoleOutputType

Value	Description
`Normal`	Standard output
`Trace`	Debug/trace output