{ "openapi": "3.1.0", "info": { "title": "DeploTeka Agent API", "version": "1.1.0" }, "servers": [ { "url": "https://deploteka.com" } ], "paths": { "/api/agent/v1/tenants/{tenantId}/shopify/capabilities": { "get": { "operationId": "shopifyAccessCapabilities", "description": "Requires collaboration:read. Returns supported permission names.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Successful operation; inspect status, freshness and permissionVerification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" } } } }, "400": { "description": "Invalid bounded input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Absent resource or unusable credential; deliberately indistinguishable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Connection/consent or request conflict; do not retry blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; honor Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait before the next request", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No trustworthy provider result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/v1/tenants/{tenantId}/shopify/access": { "get": { "operationId": "shopifyAccessCheck", "description": "Requires collaboration:read. Asks Shopify for the current relationship. Specific permission scopes are not verified.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "name": "shopDomain", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Successful operation; inspect status, freshness and permissionVerification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Observation" } } } }, "400": { "description": "Invalid bounded input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Absent resource or unusable credential; deliberately indistinguishable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Connection/consent or request conflict; do not retry blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; honor Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait before the next request", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No trustworthy provider result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/v1/tenants/{tenantId}/shopify/access-requests": { "post": { "operationId": "shopifyAccessRequest", "description": "Requires collaboration:write. Caller context is traceability, not authority. Sends exactly the listed permissions. Reuse one key for one intent; never change keys to retry an unknown outcome.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Successful operation; inspect status, freshness and permissionVerification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "Invalid bounded input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Absent resource or unusable credential; deliberately indistinguishable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Connection/consent or request conflict; do not retry blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; honor Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait before the next request", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No trustworthy provider result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequest" } } } } } }, "/api/agent/v1/tenants/{tenantId}/shopify/access-requests/{requestId}": { "get": { "operationId": "shopifyAccessRequestStatus", "description": "Requires collaboration:read. Stored receipt only; updatedAt states freshness.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; inspect status, freshness and permissionVerification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "Invalid bounded input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Absent resource or unusable credential; deliberately indistinguishable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Connection/consent or request conflict; do not retry blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; honor Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait before the next request", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No trustworthy provider result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/v1/tenants/{tenantId}/shopify/access-requests/{requestId}/refresh": { "post": { "operationId": "shopifyAccessRequestRefresh", "description": "Requires collaboration:read. Reconciles evidence without resending. Does not verify individual permissions.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; inspect status, freshness and permissionVerification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "Invalid bounded input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Absent resource or unusable credential; deliberately indistinguishable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Connection/consent or request conflict; do not retry blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; honor Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait before the next request", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No trustworthy provider result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/api/agent/v1/tenants/{tenantId}/workspace/apps": { "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "description": "Pass nextCursor from the previous page of this collection.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Workspace record", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "status" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "name": { "type": "string" }, "status": { "type": [ "string", "null" ] } } } }, "nextCursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid bounded input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Absent resource or unusable credential; deliberately indistinguishable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; honor Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait before the next request", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No trustworthy provider result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "workspaceAppsList", "description": "Requires workspace:read. List workspace app definitions." } }, "/api/agent/v1/tenants/{tenantId}/workspace/stores": { "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "description": "Pass nextCursor from the previous page of this collection.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Workspace record", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "shopDomain", "status" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "shopDomain": { "type": "string" }, "status": { "type": "string" } } } }, "nextCursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid bounded input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Absent resource or unusable credential; deliberately indistinguishable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; honor Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait before the next request", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No trustworthy provider result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "workspaceStoresList", "description": "Requires workspace:read. List workspace stores and their recorded status." } }, "/api/agent/v1/tenants/{tenantId}/workspace/releases/{releaseId}": { "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "name": "releaseId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Workspace record", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "masterAppId", "state", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "masterAppId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "state": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid bounded input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Absent resource or unusable credential; deliberately indistinguishable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; honor Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait before the next request", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No trustworthy provider result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "workspaceReleaseStatus", "description": "Requires workspace:read. Read a saved fleet release by ID." } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Opaque scoped resident service credential: product deploteka, environment production. Browser sessions and legacy unscoped keys are refused." } }, "schemas": { "Context": { "type": "object", "additionalProperties": false, "required": [ "system", "projectRef", "taskRef" ], "properties": { "system": { "type": "string", "enum": [ "danyaos", "constellation", "other" ] }, "projectRef": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$" }, "taskRef": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "NOT_FOUND", "INVALID_INPUT", "IDEMPOTENCY_CONFLICT", "ACTIVE_REQUEST_CONFLICT", "CONNECTION_REQUIRED", "PROVIDER_UNAVAILABLE", "UNAVAILABLE", "RATE_LIMITED" ] } } }, "AccessRequest": { "type": "object", "additionalProperties": false, "required": [ "shopDomain", "context", "permissions", "idempotencyKey" ], "properties": { "shopDomain": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]*\\.myshopify\\.com$" }, "context": { "$ref": "#/components/schemas/Context" }, "permissions": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "type": "string" } }, "idempotencyKey": { "type": "string", "maxLength": 200 }, "collaboratorCode": { "type": "string", "pattern": "^\\d{4}$", "writeOnly": true }, "requestMode": { "type": "string", "enum": [ "access", "additional_permissions" ], "default": "access", "description": "Explicit expansion attempts dispatch for existing approved relationships. Relationship-only refresh cannot verify the added rights." } } }, "Observation": { "type": "object", "required": [ "shopDomain", "relationship", "permissionVerification", "checkedAt" ], "properties": { "shopDomain": { "type": "string" }, "relationship": { "enum": [ "approved", "pending", "none" ] }, "permissionVerification": { "const": "not_verified" }, "checkedAt": { "type": "string", "format": "date-time" } } }, "Receipt": { "type": "object", "required": [ "requestId", "shopDomain", "context", "requestedPermissions", "status", "permissionVerification", "providerCode", "nextAction", "createdAt", "updatedAt" ], "properties": { "requestId": { "type": "string" }, "shopDomain": { "type": "string" }, "context": { "$ref": "#/components/schemas/Context" }, "requestedPermissions": { "type": "array", "items": { "type": "string" } }, "status": { "enum": [ "dispatching", "pending", "granted", "refused", "unknown" ] }, "permissionVerification": { "const": "not_verified" }, "providerCode": { "type": [ "string", "null" ] }, "nextAction": { "enum": [ "wait_for_merchant", "verify_required_permissions", "reconcile_before_retry", "review_refusal", "poll" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "requestMode": { "type": "string", "enum": [ "access", "additional_permissions" ], "description": "Persisted request intent; legacy receipts default to access." } } }, "Capabilities": { "type": "object", "required": [ "version", "provider", "permissions", "scopes" ], "properties": { "version": { "const": "1" }, "provider": { "const": "shopify" }, "permissions": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "requestModes": { "type": "array", "maxItems": 2, "items": { "type": "string", "enum": [ "access", "additional_permissions" ] } } } } } } }