PUT/api/ext/{extensionId}/{path}

Forward PUT request to extension runner

Tenant-scoped extension gateway endpoint that forwards PUT requests to an installed extension runner. The gateway resolves the tenant from x-alga-tenant, x-tenant-id, session cookie, or DEV_TENANT_ID in development; verifies the extension is installed and enabled for that tenant; forwards selected headers, query parameters, and an optional opaque body to RUNNER_BASE_URL /v1/execute; and relays the runner response. For PUT requests the body is limited to 10 MB, base64-encoded, and forwarded as http.body_b64. Clients should provide x-idempotency-key for safe retries; otherwise the gateway falls back to a generated request ID. The gateway currently has a placeholder access check and does not enforce per-extension RBAC beyond tenant install resolution.

Path parameters

extensionIdstringRequired

Extension identifier from the URL. This may be a registry/install UUID or a publisher.name slug, resolved case-insensitively.

pathstringOptional

Remaining extension endpoint path after extensionId. The gateway forwards this path to the runner unchanged.

Header parameters

x-request-idstring <uuid>Optional

Optional request ID. The gateway generates a UUID when absent and forwards it to the runner.

x-idempotency-keystringOptional

Optional idempotency key for non-GET methods. The gateway falls back to x-request-id when absent and forwards the key to the runner.

x-alga-tenantstringOptional

Internal tenant header used for tenant resolution before session fallback.

x-tenant-idstringOptional

Legacy tenant header accepted for tenant resolution before session fallback.

Request body

Content type: application/json · schema ExtensionOpaqueRequest

object

Extension-specific request body. The gateway treats this as opaque, enforces a 10 MB limit for non-GET methods, base64-encodes it, and forwards it to the extension runner.

Response body

Success response 200 · schema ExtensionOpaqueResponse

object

Extension-specific response relayed from the runner. Status code, content type, and body are controlled by the extension.

Response codes

200

Runner response relayed by the gateway. The actual status can vary by extension contract.

204

Runner returned no content, or CORS preflight for OPTIONS requests on this gateway path.

404

Extension is not installed or not enabled for the resolved tenant.

413

Request body exceeds the 10 MB gateway limit.

500

Tenant could not be resolved or another internal gateway error occurred.

502

Runner call failed, runner response was empty/invalid, or install context was incomplete.

PUT /api/ext/{extensionId}/{path}

cURL

curl -X PUT "https://algapsa.com/api/ext/{extensionId}/{path}" \
  -H "X-API-Key: $ALGA_API_KEY" \
  -H "x-request-id: 01HN2K7VRB9PQ3Y0000000000" \
  -H "x-idempotency-key: string" \
  -H "x-alga-tenant: string" \
  -H "x-tenant-id: string" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript

const response = await fetch("https://algapsa.com/api/ext/{extensionId}/{path}", {
  method: "PUT",
  headers: {
    "X-API-Key": "$ALGA_API_KEY",
    "x-request-id": "01HN2K7VRB9PQ3Y0000000000",
    "x-idempotency-key": "string",
    "x-alga-tenant": "string",
    "x-tenant-id": "string",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({})
});
const data = await response.json();

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Put, "https://algapsa.com/api/ext/{extensionId}/{path}");
request.Headers.TryAddWithoutValidation("X-API-Key", "$ALGA_API_KEY");
request.Headers.TryAddWithoutValidation("x-request-id", "01HN2K7VRB9PQ3Y0000000000");
request.Headers.TryAddWithoutValidation("x-idempotency-key", "string");
request.Headers.TryAddWithoutValidation("x-alga-tenant", "string");
request.Headers.TryAddWithoutValidation("x-tenant-id", "string");
request.Headers.TryAddWithoutValidation("Content-Type", "application/json");
request.Content = new StringContent(@"{}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

200 OK·application/json

{}