Invoke a developer application

An Application Invocation uses a stable applicationId and operation. The active release resolves the worker URL, container address, and internal HTTP path.

GridNexa validates identity, publication state, manifest, schema, quota, and billing before dispatching the current release.

The application needs an active release that declares operations, input constraints, and a runtime endpoint.

• Load Balancer resolves operation to a worker HTTP path.
• Queue writes operation and input to a task handled by your handler.
• Publish a new release when operations, images, or runtime configuration change.

Users and platform experiences authenticate with a user session, not a developer gnx_ key. Use a stable Idempotency-Key for retries.

curl -X POST "$GRIDNEXA_API_BASE_URL/v1/apps/{applicationId}/invocations" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: app-call-001" \
  -d '{
    "operation": "chat",
    "input": {
      "messages": [{"role": "user", "content": "Hello"}]
    }
  }'

A short Load Balancer call can complete inline. Queue persists a task and normally returns 202. Status is read from the GridNexa Invocation.

When an LB application creates its own asynchronous task, the platform Invocation and application task are recorded separately. Later status checks use the read-only operation declared by the release.

An HTTP worker or Queue handler can call /v1/invoke with the application's developer key. This composes the flows: a user invokes the app, and the app invokes a platform model.

User / marketplace experience
  -> application invocation
  -> your Load Balancer service or Queue handler
  -> POST /v1/invoke with the application's gnx_ key
  -> model result
  -> application result

A complete Application Invocation can be used to check the call flow before submission.

• Unpublished apps reject public calls.
• The operation exists in the active release.
• Repeated idempotency keys resolve to the original execution.
• Queue calls return a queryable Invocation ID.
• Failures retain requestId without exposing secrets in logs.