Table of contents
Official Content
  • This documentation is valid for:

This API allows you to create Instances to execute Agentic Processes.

Check the generic variables required to call the API.

Endpoints

Method Path Description
POST /processes/instances Starts a new Instance of an Agentic Process that has a Start node of type ‘User’.
GET /processes/{idOrName}/instances Lists Instances of a given Agentic Process.
GET /processes/instances/{instanceId} Retrieves high-level information about a specific instance.
GET /processes/instances/{instanceId}/trace Retrieves the execution trace (history) of an instance.
POST /processes/instances/{instanceId}/subject Updates the Instance subject (human-readable title).
POST /processes/instances/{instanceId}/variables Sets or updates the value for a variable for all Instances.
POST /processes/instances/{instanceId}/signal Sends a user-event signal to the instance.
POST /processes/instances/{instanceId}/abort Aborts a running Instance.
POST /process/instance/artifacts/upload Allows you to upload multiple files, and include metadata to create an instance.
GET /threads/{threadId} Tracks the Agentic Process Instance and Artifacts associated with a thread.

Authentication

All endpoints require authentication using one of the following:

  • Authorization: Bearer $GEAI_APITOKEN
  • Authorization: Bearer $OAuth_accesstoken

For $OAuth_accesstoken, you must also include the header: ProjectId: $GEAI_PROJECT_ID

Some endpoints may require additional headers such as:

  • Content-Type: application/json when a body is sent.
  • Accept: application/json only when you need a JSON response body.

POST /processes/instances

Starts a new Instance of an Agentic Process that has a Start node of type ‘User’.

Request

  • Method: POST
  • Path: $BASE_URL/v2/processes/instances/

Request Body

{
  "instanceDefinition": {
    "process": "string",
    "subject": "string",
    "variables": {
      "key": "string",
      "value": "string"
    },
    "revision": integer
  }
}

Response

{
  "createdAt": "string",
  "id": "string",
  "process": {
    "id": "string",
    "isDraft":  boolean,
    "name": "string",
    "revision": integer,
    "version": integer
  },
  "status": "string",
  "subject": "string"
}

cURL Sample

curl -X POST "$BASE_URL/v2/processes/instances/{idOrName}" \
  -H 'Authorization: Bearer $GEAI_APITOKEN' \
  -H 'ProjectId: $GEAI_PROJECTID' \
  -H 'content-Type: application/json' \
  -d '{
    "instanceDefinition": {
      "process": "LoopProcess2",
      "subject": "Test_download_postman",
      "variables": 
        {
          "key": "UserTopic",
          "value": "Filosofia"
        }
      ,
      "revision": 83
    }
  }'

GET /processes/{instanceId}/instances

This endpoint allows you to retrieve a paginated list of Instances for a specific Agentic Process.

Parameters

Name Type Description
start integer The starting index for pagination.
count integer The number of Instances to retrieve.

Request

  • Method: GET
  • Path: /v2/processes/{instanceId}/instances
  • Body: Empty

Response

{
  "instances": 
    {
      "createdAt": "string",          //  Date-time when the Instance was created.
      "id": "string",                 // Unique identifier for the Agentic Process Instance.
      "owner": "string",              // User or system identifier that owns the Instance.
      "process": {
        "id": "string",               // Unique identifier for the Agentic Process definition.
        "isDraft": boolean,           // Indicates if the Agentic Process definition is a draft.
        "name": "string",             // Name of the Agentic Process definition.
        "revision": integer,          // Revision number of the Agentic Process definition.
        "version": integer            // Version number of the Agentic Process definition.
      },
      "status": "string",             // Status of the Instance (e.g., "Completed").
      "subject": "string"             // Subject or context for the Instance.
    }
    // ... more Agentic Processes Instances
  
}

cURL Sample

curl -X GET "$BASE_URL/v2/processes/{instanceId}/instances?start=0&count=10" \
  -H 'Authorization: Bearer $GEAI_APITOKEN' \
  -H 'ProjectID: $GEAI_PROJECT_ID'

GET /processes/instances/{instanceId}

Allows you to retrieve detailed information about a specific Agentic Process Instance, and inspect the metadata, status, and configuration of a particular execution of an Agentic Process.

Request

  • Method: GET
  • Path: $BASE_URL/v2/processes/instances/{instanceId}
  • Body: Empty

Response

{
  "createdAt": "string",          // Date-time when the Instance was created.
  "id": "string",                 // Unique identifier for the Agentic Process Instance.
  "owner": "string",              // User or system identifier that owns the Instance.
  "process": {
    "id": "string",               // Unique identifier for the Agentic Process definition.
    "isDraft": boolean,           // Indicates if the Agentic Process definition is a draft.
    "name": "string",             // Name of the Agentic Process definition.
    "revision": integer,          // Revision number of the Agentic Process definition.
    "version": integer            // Version number of the Agentic Process definition.
  },
  "status": "string",             // Status of the Instance (e.g., "Completed").
  "subject": "string"             // Subject or context for the Instance.
}

cURL Sample

curl -X GET "BASE_URL/v2/processes/instances/{instanceId}" \
  -H 'Authorization: Bearer $GEAI_APITOKEN' \
  -H 'Projectid: GEAI_PROJECTID'

GET /processes/instances/{instanceId}/trace

Allows you to retrieve the full execution trace of a specific Agentic Process Instance, including the execution history of each activity, generated Artifacts, Agentic Process variables, and metadata.

Request

  • Method: GET
  • Path: $BASE_URL/v2/processes/instances/{instanceId}/trace
  • Body: Empty

Response

{
  "History": 
    {
      "activity": "string",                // Name of the activity or event.
      "endedAt": "string",                 // Date-time when the activity ended.
      "key": "string",                     // Unique key for the activity or event.
      "startedAt": "string",               //  Date-time when the activity started.
      "status": "string",                  // Status of the activity (e.g., "Completed").
      "type": "string",                    // Type of activity (e.g., "Work-Agent", "Event-Artifact").
      "AgentJob": {                        // [Optional Agent job details for agent activities.
        "agentJob": "string",              // Unique identifier for the agent job.
        "agentJobStatus": "string"         // Status of the agent job.
      },
      "Outputs":                          // [Optional List of output Artifacts generated by this activity.
        {
          "fileId": "string",              // File identifier for the Artifact.
          "id": "string",                  // Unique identifier for the Artifact.
          "name": "string",                // Name of the Artifact.
          "type": "string",                // Artifact type identifier.
          "typeName": "string"             // Artifact type name.
        }
      ]
    }
    // ... more activity history entries
  ],
  "artifacts": 
    {
      "fileId": "string",                  // File identifier for the Artifact.
      "id": "string",                      // Unique identifier for the Artifact.
      "name": "string",                    // Name of the Artifact.
      "type": "string",                    // Artifact type identifier.
      "typeName": "string"                 // Artifact type name.
    }
    // ... more Artifacts
  ,
  "createdAt": "string",                   // ISO 8601 date-time when the Instance was created.
  "id": "string",                          // Unique identifier for the Agentic Process Instance.
  "owner": "string",                       // User or system identifier that owns the Instance.
  "process": {
    "id": "string",                        // Unique identifier for the Agentic Process definition.
    "isDraft": boolean,                    // Indicates if the Agentic Process definition is a draft.
    "name": "string",                      // Name of the Agentic Processes definition.
    "revision": integer,                   // Revision number of the Agentic Process definition.
    "version": integer                     // Version number of the Agentic Process definition.
  },
  "status": "string",                      // Status of the Instance (e.g., "Completed").
  "subject": "string",                     // Subject or context for the Instance.
  "variables": 
    {
      "key": "string",                     // Name of the Process variable.
      "value": "string"                    // Value of the Process variable.
    }
    // ... more variables
  
}

cURL Sample

curl -X GET "BASE_URL/v2/processes/instances/{instanceId}/trace" \
  -H 'Authorization: Bearer $GEAI_APITOKEN' \
  -H 'Projectid: $GEAI_PROJECTID'

PUT /processes/instances/{instanceId}/subject

Updates the subject of a specific Agentic Process Instance.

Request

  • Method: PUT
  • Path: $BASE_URL/v2/processes/instances/{instanceId}/subject

Request Body

{
  "subject": "string"
}

Response

{
  "id": "string",
  "subject": "string"
}

cURL Sample

curl -X PUT "$BASE_URL/v2/processes/instances/{instanceId}/subject" \
  -H 'Authorization: Bearer $GEAI_APITOKEN' \
  -H 'ProjectId: $GEAI_PROJECTID' \
  -H 'content-Type: application/json' \
  -d '{ "subject": "New subject" }'

POST /processes/instances/{instanceId}/variables

Allows you to assign or update the value of a single Agentic Process variable for a specific Agentic Process Instance.

Request

  • Method: POST
  • Path: $BASE_URL/v2/processes/instances/{instanceId}/variables

Request Body

  {
    "key": "string",     // Required The name of the Agentic Process variable to set. Must exist in the Agentic Process definition.
    "value": "string"    // Required The value to assign to the variable.
  }

Response

{
  "createdAt": "string",          // ISO 8601 date-time when the Instance was created.
  "id": "string",                 // Unique identifier for the Agentic Process Instance.
  "owner": "string",              // User or system identifier that owns the Instance.
  "process": {
    "id": "string",               // Unique identifier for the Agentic Process definition.
    "isDraft": boolean,           // Indicates if the Agentic Process definition is a draft.
    "name": "string",             // Name of the Agentic Process definition.
    "revision": integer,          // Revision number of the Agentic Process definition.
    "version": integer            // Version number of the Agentic Process definition.
  },
  "status": "string",             // Status of the Instance (e.g., "Running").
  "subject": "string",            // Subject or context for the Instance.
  "variables": 
    {
      "key": "string",            // Name of the Agentic Process variable.
      "value": "string"           // Value of the Agentic Process variable.
    }
    // ... more variables
  
}

cURL Sample

curl -X POST "$BASE_URL/v2/processes/instances/{instanceId}/variables" \
  -H 'Authorization: Bearer $GEAI_APITOKEN' \
  -H 'Projectid: $GEAI_PROJECTID' \
  -H 'content-type: application/json' \
  -d '{
    "key": "proposal",
    "value": "1234"
  }'

POST /processes/instances/{instanceId}/signal

Notifies an Agentic Process Instance that a user event has occurred.

Notes

  • When an activity of type User-Event is included in the Agentic Process definition, the Agentic Process Instance will pause at that activity and remain dormant until it receives a signal.
  • The signal name provided in the body must match the signal name defined in the Agentic Process definition.
  • If the Agentic Process Instance is waiting at a User-Event activity with the specified signal name, it will resume execution.
  • If the signal name does not match any waiting user event, the request will result in an error.

Request

  • Method: POST
  • Path: $BASE_URL/v2/processes/instances/{instanceId}/signal

Request Body:

  {
    "name": "string"   // Required The name of the user signal. Must match the signal name defined in the Agentic Process definition.
  }

Response

No response body.

cURL Sample

curl -X POST "$BASE_URL/v2/processes/instances/{instanceId}/signal" \
  -H "authorization: Bearer $GEAI_APITOKEN" \
  -H "content-type: application/json" \
  -H "ProjectId: $GEAI_PROJECTID" \
  -d '{
    "name": "signal_done"
  }'

POST /processes/instances/{instanceId}/abort

Aborts a running Agentic Process Instance.

Request

  • Method: POST
  • Path: $BASE_URL/v2/processes/instances/{instanceId}/abort
  • Body: Empty

Response

{
  "description": "success",
  "id": "string"
}

cURL Sample

curl -X POST "$BASE_URL/v2/processes/instances/{instanceId}/abort" \
  -H 'Authorization: Bearer $GEAI_APITOKEN' \
  -H 'ProjectId: $GEAI_PROJECTID'

POST /process/instances/artifacts/upload

Allows you to upload multiple files (Artifacts) as required by the Start event of an Agentic Process definition and to include metadata, creating a new Instance. Metadata is linked by a thread identifier, which can be used to track the Instance.

Request

  • Method: POST
  • Path:$BASE_URL/v2/process/instances/artifacts/upload

Request Body

{
  "kb": "string",                    // Required Name of the Agentic Process knowledge base (must match the process name).
  "thread": "string",                // Optional Identifier to link files, Agentic Process Instance, and jobs. If omitted, a GUID is generated.
  "instanceDefinition": {            // Optional Information for the Agentic Process Instance.
    "process": "string",             // Optional Agentic Process name (inferred from kb if omitted).
    "revision": integer,             // Optional Specific revision to use.
    "subject": "string",             // Optional Subject for the Agentic Process Instance. Defaults to the first file name if omitted.
    "variables":                    // [Optional Initial values for Agentic Process variables.
      {
        "value": "string"            // Value of the variable.
      }
    ]
  },
  "artifacts":                      // [Optional Metadata for each uploaded Artifact.
    {
      "key": "string",               // Key matching the file/artifactType.
      "properties": "string"         // JSON string with Artifact-specific properties.
    }
  ]
}

Response

{
  "artifact": 
    {
      "id": "string",                // Unique identifier for the Artifact.
      "name": "string",              // Name of the uploaded file.
      "thread": "string",            // Thread identifier linking the Artifact to the Agentic Process Instance.
      "message": "string",           // Status or informational message.
      "type": "string",              // Artifact type (must match artifactType in Agentic Process definition).
      "publicationToken": "string"   // Token for publication or further processing.
    }
    // ... more Artifacts
  
}

cURL Sample

 
curl -X POST "$BASE_URL/v2/process/instances/artifacts/upload" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Metadata: {\"kb\":\"my_process\",\"thread\":\"thread-12345\",\"instanceDefinition\":{\"subject\":\"Approve Order #4567\",\"variables\":{\"key\":\"customerId\",\"value\":\"CUST-789\"},{\"key\":\"priority\",\"value\":\"high\"}},\"artifacts\":{\"key\":\"invoice\",\"properties\":\"{\\\"invoiceNumber\\\":\\\"INV-2025\\\",\\\"amount\\\":\\\"1000\\\",\\\"currency\\\":\\\"USD\\\"}\"}}" \
  -F "file_typeA=@/path/to/metadata.txt" \
  -F "file_typeB=@/path/to/specs.txt"

GET /threads/{threadId}

Tracks the Agentic Process Instance and Artifacts associated with a thread.

Request

  • Method: GET
  • Path: $BASE_URL/v2/threads/{threadId}
  • Body: Empty

Response

{
  "Information": {
    "Duration": integer,
    "Page": integer,
    "PageSize": integer,
    "Total": integer
  },
  "Items": 
    {
      "artifact": {
        "id": "string",
        "name": "string"
      },
      "timestamp": "string",         // date-time.
      "type": "artifact"
    },
    {
      "processInstance": {
        "createdAt": "string",
        "id": "string",
        "process": {
          "id": "string"
        },
        "subject": "string"
      },
      "timestamp": "string",
      "type": "process_instance"
    }
    // ... more items
  ,
  "count": integer
}

cURL Sample

curl -X GET "$BASE_URL/threads/{threadId}" \
  -H 'Authorization: Bearer $GEAI_APITOKEN'
—
Last update: 19 December 2025 by lmigone
Last update: December 2025 | © GeneXus. All rights reserved. GeneXus Powered by Globant