# Organization Management API Administer organization members and usage limits, and review enterprise control history. ## List organization computer secret names `GET /api/v0/organization/computer-secrets` Lists names of write-only secrets shared by managed computers in the authenticated organization. Persisted plaintext values are never returned. ```bash curl 'https://api.factory.ai/api/v0/organization/computer-secrets' \ -H 'Authorization: Bearer $FACTORY_API_KEY' ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "secrets": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ], "additionalProperties": false } } }, "required": [ "secrets" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `404` - Response for status 404 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `503` - Response for status 503 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Update organization computer secrets `PATCH /api/v0/organization/computer-secrets` Atomically upserts and deletes write-only secrets shared by managed computers in the authenticated organization. Responses include names only. ```bash curl -X PATCH 'https://api.factory.ai/api/v0/organization/computer-secrets' \ -H 'Authorization: Bearer $FACTORY_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ ... }' ``` **Request body** (optional) ```json { "type": "object", "properties": { "createOnly": { "type": "boolean" }, "upsert": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$", "maxLength": 128, "description": "Uppercase POSIX environment variable name." }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "key", "value" ], "additionalProperties": false }, "maxItems": 100 }, "delete": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$", "maxLength": 128 }, "maxItems": 100 } }, "required": [ "upsert", "delete" ], "additionalProperties": false } ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "secrets": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ], "additionalProperties": false } } }, "required": [ "secrets" ], "additionalProperties": false } ``` **Response:** `400` - Response for status 400 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `404` - Response for status 404 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `409` - Response for status 409 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `503` - Response for status 503 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## List enterprise control change history `GET /api/v0/organization/enterprise-controls/history` Returns a paginated list of enterprise control setting changes for the organization, ordered by revision descending. Properties for the `settings` object may be added, removed, or renamed between API versions. Clients should parse it as a generic JSON object. ```bash curl 'https://api.factory.ai/api/v0/organization/enterprise-controls/history' \ -H 'Authorization: Bearer $FACTORY_API_KEY' ``` **Parameters** - `limit` (`string`) - Query parameter. Maximum number of items to return (1-100) - `cursor` (`string`) - Query parameter. Cursor for pagination **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "revision": { "type": "integer", "description": "Revision number of the change" }, "settings": { "type": "object", "properties": { "sessionDefaultSettings": { "type": "object", "properties": { "model": { "type": "string" }, "reasoningEffort": { "type": "string", "enum": [ "none", "dynamic", "off", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "interactionMode": { "type": "string", "enum": [ "auto", "spec", "agi", "mission" ] }, "autonomyLevel": { "type": "string", "enum": [ "off", "low", "medium", "high" ] }, "autonomyMode": { "type": "string", "enum": [ "normal", "spec", "auto-low", "auto-medium", "auto-high" ], "description": "Deprecated: use interactionMode + autonomyLevel instead." }, "specModeModel": { "type": "string" }, "specModeReasoningEffort": { "type": "string", "enum": [ "none", "dynamic", "off", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "missionOrchestratorModel": { "type": "string" }, "missionOrchestratorReasoningEffort": { "type": "string", "enum": [ "none", "dynamic", "off", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "missionModelSettings": { "type": "object", "properties": { "workerModel": { "type": "string" }, "workerReasoningEffort": { "type": "string", "enum": [ "none", "dynamic", "off", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "validationWorkerModel": { "type": "string" }, "validationWorkerReasoningEffort": { "type": "string", "enum": [ "none", "dynamic", "off", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "maxAutonomyLevel": { "type": "string", "enum": [ "off", "low", "medium", "high" ] }, "subagentAutonomyLevel": { "type": "string", "enum": [ "off", "low", "medium", "high", "inherit" ] }, "subagentModelSettings": { "type": "object", "properties": { "lightModel": { "type": "string" }, "lightReasoningEffort": { "type": "string", "enum": [ "none", "dynamic", "off", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "mediumModel": { "type": "string" }, "mediumReasoningEffort": { "type": "string", "enum": [ "none", "dynamic", "off", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "heavyModel": { "type": "string" }, "heavyReasoningEffort": { "type": "string", "enum": [ "none", "dynamic", "off", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "mcpAutonomyOverrides": { "type": "object", "additionalProperties": { "type": "object", "properties": { "defaultLevel": { "type": "string", "enum": [ "low", "medium", "high" ] }, "tools": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "low", "medium", "high" ] } } }, "additionalProperties": false } }, "mcpAutonomyUrlOverrides": { "type": "array", "items": { "type": "object", "properties": { "urlPattern": { "type": "string", "minLength": 1 }, "defaultLevel": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "required": [ "urlPattern", "defaultLevel" ], "additionalProperties": false } }, "builtInToolAutonomyOverrides": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "cloudSessionSync": { "type": "boolean" }, "allowSessionTitleInMetadata": { "type": "boolean" }, "cloudConfigSync": { "type": "boolean" }, "cloudItemPull": { "type": "boolean" }, "voiceDictationEnabled": { "type": "boolean" }, "routedModelVisibilityPolicy": { "type": "string", "enum": [ "off_for_everyone", "users_choose", "on_for_everyone" ] }, "imageGenerationEnabled": { "type": "boolean" }, "imageGenerationModel": { "type": "string" }, "imageGenerationAllowedModelIds": { "type": "array", "items": { "type": "string" } }, "webSearchDisabled": { "type": "boolean" }, "readinessReportUpload": { "type": "string", "enum": [ "ask", "always", "never" ] }, "wikiCloudSync": { "type": "boolean" }, "advancedAnalyticsEnabled": { "type": "boolean" }, "cycleTimeBoundaries": { "type": "object", "properties": { "linear": { "type": "object", "additionalProperties": { "type": "object", "properties": { "startStatuses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "id", "name" ], "additionalProperties": false }, "minItems": 1 }, "endStatuses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "id", "name" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "startStatuses", "endStatuses" ], "additionalProperties": false } }, "jira": { "type": "object", "additionalProperties": { "type": "object", "properties": { "startStatuses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "id", "name" ], "additionalProperties": false }, "minItems": 1 }, "endStatuses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "id", "name" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "startStatuses", "endStatuses" ], "additionalProperties": false } } }, "additionalProperties": false }, "includeCoAuthoredByDroid": { "type": "boolean" }, "enableDroidShield": { "type": "boolean" }, "enableOneHourAnthropicCaching": { "type": "boolean" }, "droidShield20OptIn": { "type": "boolean" }, "ideAutoConnect": { "type": "boolean" }, "outputStyle": { "type": "string", "minLength": 1, "maxLength": 1024 }, "commandAllowlist": { "type": "array", "items": { "type": "string" } }, "commandDenylist": { "type": "array", "items": { "type": "string" } }, "commandBlocklist": { "type": "array", "items": { "type": "string" } }, "customModels": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "id": { "type": "string" }, "index": { "type": "number" }, "baseUrl": { "type": "string" }, "apiKey": { "type": "string" }, "apiKeyHelper": { "type": "string" }, "apiKeyHelperTtlMs": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "authMode": { "type": "string", "enum": [ "provider-default", "bearer" ], "description": "Authentication mode for the configured credential. \"bearer\" uses the Anthropic SDK authToken path; omitted or \"provider-default\" preserves native provider authentication." }, "provider": { "type": "string", "enum": [ "anthropic", "openai", "generic-chat-completion-api", "factory", "google", "xai", "bedrock-converse" ] }, "displayName": { "type": "string" }, "maxContextLimit": { "type": "number" }, "enableThinking": { "type": "boolean" }, "thinkingMaxTokens": { "type": "number" }, "maxOutputTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "none", "dynamic", "off", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "extraHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "extraArgs": { "type": "object", "additionalProperties": {} }, "noImageSupport": { "type": "boolean" }, "bedrock": { "type": "object", "properties": { "authMethod": { "type": "string", "enum": [ "aws-credentials", "credentials-command", "environment-api-key" ] }, "awsProfile": { "type": "string" }, "awsRegion": { "type": "string", "minLength": 1 }, "bedrockBaseUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}" } ] }, "awsAuthRefresh": { "type": "string" }, "awsCredentialExport": { "type": "string" }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false }, "baseModelId": {}, "useInRouter": { "type": "boolean", "description": "Opt this model into Auto Model routing when baseModelId matches a built-in model and organization policy permits BYOK routing." } }, "required": [ "model", "provider" ] }, { "type": "object", "properties": { "fileEditToolProfile": { "type": "string", "enum": [ "apply-patch", "create-edit" ], "description": "Optional file-tool override for exceptional model harnesses. Use \"apply-patch\" to advertise ApplyPatch or \"create-edit\" to advertise Create and Edit. This setting takes precedence over registry overrides, registry provider identity, and GPT/Codex/o-series name inference." } } } ] } }, "hideDisabledModels": { "type": "boolean" }, "modelPolicy": { "type": "object", "properties": { "allowedModelIds": { "type": "array", "items": { "type": "string" } }, "blockedModelIds": { "type": "array", "items": { "type": "string" } }, "allowCustomModels": { "type": "boolean" }, "allowedBaseUrls": { "type": "array", "items": { "type": "string" } }, "allowAllFactoryModels": { "type": "boolean" }, "isFastModelsAllowed": { "type": "boolean" }, "requireExplicitOptInModelIds": { "type": "array", "items": { "type": "string" } }, "allowFactoryRouterByok": { "type": "boolean" }, "factoryRouterByokOnly": { "type": "boolean" } }, "additionalProperties": false }, "mcpPolicy": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "allowlist": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "missionPolicy": { "type": "object", "properties": { "restrictedAccess": { "type": "boolean", "default": false }, "allowedUserIds": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "userModelPolicies": { "type": "object", "additionalProperties": { "type": "object", "properties": { "allowedModelIds": { "type": "array", "items": { "type": "string" } }, "blockedModelIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "allowedModelIds", "blockedModelIds" ], "additionalProperties": false } }, "enabledPlugins": { "type": "object", "additionalProperties": { "type": "boolean" } }, "strictEnabledPlugins": { "type": "boolean" }, "disabledSkills": { "type": "array", "items": { "type": "string" } }, "extraKnownMarketplaces": { "type": "object", "additionalProperties": { "type": "object", "properties": { "source": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "github" ] }, "repo": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$" }, "ref": { "type": "string", "minLength": 1 }, "sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$" } }, "required": [ "source", "repo" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" }, "ref": { "type": "string", "minLength": 1 }, "sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$" } }, "required": [ "source", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "local" ] }, "path": { "type": "string" } }, "required": [ "source", "path" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "git-subdir" ] }, "url": { "type": "string" }, "path": { "type": "string" }, "ref": { "type": "string", "minLength": 1 }, "sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$" } }, "required": [ "source", "url", "path" ], "additionalProperties": false } ] } }, "required": [ "source" ], "additionalProperties": false } }, "strictKnownMarketplaces": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "github" ] }, "repo": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$" }, "ref": { "type": "string", "minLength": 1 }, "sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$" } }, "required": [ "source", "repo" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" }, "ref": { "type": "string", "minLength": 1 }, "sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$" } }, "required": [ "source", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "local" ] }, "path": { "type": "string" } }, "required": [ "source", "path" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "git-subdir" ] }, "url": { "type": "string" }, "path": { "type": "string" }, "ref": { "type": "string", "minLength": 1 }, "sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$" } }, "required": [ "source", "url", "path" ], "additionalProperties": false } ] } }, "networkPolicy": { "type": "object", "properties": { "allowedIps": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "allowedIps" ], "additionalProperties": false }, "sandbox": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "per-command", "whole-process" ] }, "filesystem": { "type": "object", "properties": { "allowWrite": { "type": "array", "items": { "type": "string" } }, "allowRead": { "type": "array", "items": { "type": "string" } }, "denyWrite": { "type": "array", "items": { "type": "string" } }, "denyRead": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "network": { "type": "object", "properties": { "allowedDomains": { "type": "array", "items": { "type": "string" } }, "deniedDomains": { "type": "array", "items": { "type": "string" } }, "allowUnixSockets": { "type": "array", "items": { "type": "string" } }, "allowAllUnixSockets": { "type": "boolean" }, "allowLocalBinding": { "type": "boolean" }, "httpProxyPort": { "type": "number" }, "socksProxyPort": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "allowManagedHooksOnly": { "type": "boolean" }, "hooks": { "type": "object", "properties": { "PreToolUse": { "type": "array", "items": { "type": "object", "properties": { "matcher": { "type": "string" }, "commandRegex": { "type": "string" }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "command": { "type": "string" }, "timeout": { "type": "number" }, "preserveRiskLevel": { "type": "boolean" } }, "required": [ "type", "command" ], "additionalProperties": false } } }, "required": [ "hooks" ], "additionalProperties": false } }, "PostToolUse": { "type": "array", "items": { "type": "object", "properties": { "matcher": { "type": "string" }, "commandRegex": { "type": "string" }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "command": { "type": "string" }, "timeout": { "type": "number" }, "preserveRiskLevel": { "type": "boolean" } }, "required": [ "type", "command" ], "additionalProperties": false } } }, "required": [ "hooks" ], "additionalProperties": false } }, "Notification": { "type": "array", "items": { "type": "object", "properties": { "matcher": { "type": "string" }, "commandRegex": { "type": "string" }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "command": { "type": "string" }, "timeout": { "type": "number" }, "preserveRiskLevel": { "type": "boolean" } }, "required": [ "type", "command" ], "additionalProperties": false } } }, "required": [ "hooks" ], "additionalProperties": false } }, "UserPromptSubmit": { "type": "array", "items": { "type": "object", "properties": { "matcher": { "type": "string" }, "commandRegex": { "type": "string" }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "command": { "type": "string" }, "timeout": { "type": "number" }, "preserveRiskLevel": { "type": "boolean" } }, "required": [ "type", "command" ], "additionalProperties": false } } }, "required": [ "hooks" ], "additionalProperties": false } }, "Stop": { "type": "array", "items": { "type": "object", "properties": { "matcher": { "type": "string" }, "commandRegex": { "type": "string" }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "command": { "type": "string" }, "timeout": { "type": "number" }, "preserveRiskLevel": { "type": "boolean" } }, "required": [ "type", "command" ], "additionalProperties": false } } }, "required": [ "hooks" ], "additionalProperties": false } }, "SubagentStop": { "type": "array", "items": { "type": "object", "properties": { "matcher": { "type": "string" }, "commandRegex": { "type": "string" }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "command": { "type": "string" }, "timeout": { "type": "number" }, "preserveRiskLevel": { "type": "boolean" } }, "required": [ "type", "command" ], "additionalProperties": false } } }, "required": [ "hooks" ], "additionalProperties": false } }, "PreCompact": { "type": "array", "items": { "type": "object", "properties": { "matcher": { "type": "string" }, "commandRegex": { "type": "string" }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "command": { "type": "string" }, "timeout": { "type": "number" }, "preserveRiskLevel": { "type": "boolean" } }, "required": [ "type", "command" ], "additionalProperties": false } } }, "required": [ "hooks" ], "additionalProperties": false } }, "SessionStart": { "type": "array", "items": { "type": "object", "properties": { "matcher": { "type": "string" }, "commandRegex": { "type": "string" }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "command": { "type": "string" }, "timeout": { "type": "number" }, "preserveRiskLevel": { "type": "boolean" } }, "required": [ "type", "command" ], "additionalProperties": false } } }, "required": [ "hooks" ], "additionalProperties": false } }, "SessionEnd": { "type": "array", "items": { "type": "object", "properties": { "matcher": { "type": "string" }, "commandRegex": { "type": "string" }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "command": { "type": "string" }, "timeout": { "type": "number" }, "preserveRiskLevel": { "type": "boolean" } }, "required": [ "type", "command" ], "additionalProperties": false } } }, "required": [ "hooks" ], "additionalProperties": false } }, "hooksDisabled": { "type": "boolean" }, "showHookOutput": { "type": "boolean" } }, "additionalProperties": false }, "restrictMemberVisibility": { "type": "boolean" }, "restrictApiKeyCreationToManagers": { "type": "boolean" }, "localComputersEnabled": { "type": "boolean" }, "managedComputersEnabled": { "type": "boolean" }, "managedComputersAllowedEmails": { "type": "array", "items": { "type": "string" } }, "byomComputersEnabled": { "type": "boolean" }, "byomComputersAllowedEmails": { "type": "array", "items": { "type": "string" } }, "openComputeEnabled": { "type": "boolean" }, "openComputeAllowedEmails": { "type": "array", "items": { "type": "string" } }, "disabledUserIntegrations": { "type": "object", "properties": { "bitbucket-personal": { "type": "boolean" } }, "additionalProperties": false }, "evaluationsEnabled": { "type": "boolean" }, "evaluationsAllowedEmails": { "type": "array", "items": { "type": "string" } }, "disableAutoUpdate": { "type": "boolean" }, "personaSettings": { "type": "object", "properties": { "enabledRoles": { "type": "array", "items": { "type": "string", "enum": [ "engineering", "product", "finance", "marketing", "sales", "operations", "design", "founder", "something-else" ] }, "minItems": 1, "maxItems": 9 }, "personaConnectors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "airtable", "amazon_s3", "amplitude", "apollo", "asana", "ashby", "axiom", "axiom_co", "axiom_mcp_server", "bitly", "calendly", "clay", "clickup", "cloudflare", "coda", "confluence", "contentful", "databricks", "datadog", "doordash", "dropbox", "dynamics365", "exa", "figma", "firecrawl", "fireflies", "github", "gitlab", "gmail", "gong", "google_calendar", "google_docs", "google_drive", "google_maps", "google_sheets", "google_slides", "grafana", "granola", "greenhouse", "hex", "hubspot", "jira", "jira_service_management", "linear", "looker", "metabase", "microsoft_teams", "microsoft_teams_gcc", "monday", "notion", "onedrive", "onedrive_gcc", "onenote", "oracle_hcm", "oracle_sales_cloud", "oracle_scm", "okta", "oura", "outlook", "pagerduty", "paypal", "posthog", "pubmed", "pylon", "render", "rootly", "salesforce", "sendgrid", "sentry", "servicenow", "sharepoint", "sharepoint_gcc", "shopify", "slack", "snowflake", "spotify", "statsig", "statsig_mcp", "stripe", "supabase", "teamwork", "trello", "vercel", "whoop", "wordpress", "workday", "x", "zendesk", "zendesk_sell", "zoom" ] }, "minItems": 1, "maxItems": 20 } }, "personaPlugins": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20 } } }, "additionalProperties": false }, "sessionRetentionDays": { "type": "integer", "minimum": 14, "maximum": 365 }, "factoryRouterGuidance": { "type": "string", "maxLength": 2000 }, "factoryRouterRules": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "string", "maxLength": 300 }, "guidance": { "type": "string", "maxLength": 600 } }, "required": [ "guidance" ], "additionalProperties": false }, "maxItems": 20 }, "factoryRouterCandidates": { "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "card": { "type": "string" } }, "additionalProperties": false } }, "disableWeeklyUsageSummary": { "type": "boolean" }, "env": { "type": "object", "additionalProperties": { "type": "string" } }, "telemetry": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "logMessageContent": { "type": "boolean" }, "granularity": { "type": "string", "enum": [ "user", "aggregate" ] }, "format": { "type": "string", "enum": [ "legacy", "genai" ] }, "endpoint": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "metricExportIntervalMs": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 2147483647 } }, "additionalProperties": false }, "permissionRules": {} }, "additionalProperties": true, "description": "The managed settings snapshot at this revision. Properties may be added, removed, or renamed between API versions. Clients should parse this as a generic JSON object." }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "WorkOS user ID who made the change" }, "email": { "type": "string", "nullable": true, "description": "Email of the user who made the change" }, "name": { "type": "string", "nullable": true, "description": "Display name of the user who made the change" } }, "required": [ "id", "email", "name" ], "additionalProperties": false, "description": "The user who made the change" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the change was made" } }, "required": [ "revision", "settings", "user", "updatedAt" ], "additionalProperties": false }, "description": "List of enterprise control changes" }, "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether there are more items after this page" }, "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to use for the next page, null if no more pages" } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false } }, "required": [ "changes", "pagination" ], "additionalProperties": false } ``` **Response:** `400` - Response for status 400 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Get global user credits limit `GET /api/v0/organization/usage/limits/global` Returns the global per-user credits limit for the organization. This limit applies to all users who do not have an individual override. ```bash curl 'https://api.factory.ai/api/v0/organization/usage/limits/global' \ -H 'Authorization: Bearer $FACTORY_API_KEY' ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 0, "nullable": true, "description": "Current global per-user credits limit, or null if none is configured" } }, "required": [ "limit" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Set global user credits limit `PUT /api/v0/organization/usage/limits/global` Set the global per-user credits limit for the organization. This limit applies to all users who do not have an individual override. Pass null to remove the global limit. ```bash curl -X PUT 'https://api.factory.ai/api/v0/organization/usage/limits/global' \ -H 'Authorization: Bearer $FACTORY_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ ... }' ``` **Request body** (optional) ```json { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1000000, "nullable": true, "description": "Global per-user credits limit (minimum 1,000,000). Pass null to remove the global limit." } }, "required": [ "limit" ], "additionalProperties": false } ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 0, "nullable": true, "description": "The limit that was set, or null if it was removed" } }, "required": [ "limit" ], "additionalProperties": false } ``` **Response:** `400` - Response for status 400 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Get group credits limits `GET /api/v0/organization/usage/limits/groups` Returns the directory-group credits limits mapped for the organization. Each mapping applies the mapped limit to every synced member of the group, between their individual override and the global limit. Members of several mapped groups get the highest mapped limit. ```bash curl 'https://api.factory.ai/api/v0/organization/usage/limits/groups' \ -H 'Authorization: Bearer $FACTORY_API_KEY' ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "groupLimits": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$", "description": "Stable WorkOS directory group id. Rename-proof: renaming the group in your identity provider never changes this id, so the mapping survives." }, "name": { "type": "string", "nullable": true, "description": "Directory group display name from the IdP, or null when the group is no longer present in the synced directory" }, "limit": { "type": "integer", "minimum": 0, "nullable": true, "description": "Credits limit mapped to this group, or null if no limit is mapped" } }, "required": [ "groupId", "name", "limit" ], "additionalProperties": false }, "description": "Directory groups with mapped credits limits" } }, "required": [ "groupLimits" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Set group credits limits `PUT /api/v0/organization/usage/limits/groups` Map synced directory groups to per-member credits limits (up to 100 per request). Identify each group by its stable WorkOS group id; renaming a group in your identity provider never changes the id, so mappings survive renames. Pass null for limit to unmap a group (members fall back to the global limit). Enforcement is read-time: members pick a mapping change up at their next request, with no per-user writes. ```bash curl -X PUT 'https://api.factory.ai/api/v0/organization/usage/limits/groups' \ -H 'Authorization: Bearer $FACTORY_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ ... }' ``` **Request body** (optional) ```json { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$", "description": "Stable WorkOS directory group id. Rename-proof: renaming the group in your identity provider never changes this id, so the mapping survives." }, "limit": { "type": "integer", "minimum": 1000000, "nullable": true, "description": "Credits limit to set for members of this group (minimum 1,000,000). Pass null to unmap the group (members fall back to the global limit)." } }, "required": [ "groupId", "limit" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100, "description": "Array of group limit entries (up to 100). Each maps a synced directory group to a per-member credits limit." } }, "required": [ "groups" ], "additionalProperties": false } ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "updated": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$", "description": "Stable WorkOS directory group id. Rename-proof: renaming the group in your identity provider never changes this id, so the mapping survives." }, "limit": { "type": "integer", "minimum": 0, "nullable": true, "description": "The limit that was set, or null if the group mapping was removed" } }, "required": [ "groupId", "limit" ], "additionalProperties": false }, "description": "Successfully updated group limits" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "description": "Group id that was provided" }, "error": { "type": "string", "description": "Error message" } }, "required": [ "groupId", "error" ], "additionalProperties": false }, "description": "Errors for groups that could not be updated" } }, "required": [ "updated", "errors" ], "additionalProperties": false } ``` **Response:** `400` - Response for status 400 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Get shared monthly user limits `GET /api/v0/organization/usage/limits/shared` List configured Global Organization Limits for the authenticated root organization. Each cap applies to one human user across the root and every sub-organization, independently of existing per-org limits. Requires a human Owner API key or JWT acting in the Enterprise root and the shared-usage-limits feature. Service-account credentials are not supported. Amounts are normalized Factory credits, not millions of credits; 0 is a blocking cap. An empty list means no shared caps are configured. ```bash curl 'https://api.factory.ai/api/v0/organization/usage/limits/shared' \ -H 'Authorization: Bearer $FACTORY_API_KEY' ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "principals": { "type": "array", "items": { "type": "object", "properties": { "principalId": { "type": "string" }, "limit": { "type": "number", "nullable": true } }, "required": [ "principalId", "limit" ], "additionalProperties": false } } }, "required": [ "principals" ], "additionalProperties": false } ``` **Response:** `400` - Response for status 400 ```json { "anyOf": [ { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" }, "message": { "not": {} } }, "required": [ "detail", "status", "title" ], "additionalProperties": false }, { "type": "object", "properties": { "message": { "type": "string", "description": "Request validation error" }, "errors": { "type": "array", "items": {}, "description": "Framework validation issues, when available" } }, "required": [ "message" ], "additionalProperties": false } ] } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `404` - Response for status 404 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `429` - Response for status 429 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `503` - Response for status 503 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Set shared monthly user limits `PUT /api/v0/organization/usage/limits/shared` Set or remove Global Organization Limits for up to 100 human user IDs in the authenticated root organization. Requires a human Owner API key or JWT acting in the Enterprise root and the shared-usage-limits feature. Each principalId identifies a human user, not a service account. Amounts are normalized Factory credits (5000000 means 5M credits); 0 blocks usage and null removes the shared cap. Other shared caps and existing per-org limits are unchanged. Duplicate IDs, malformed ID/limit shapes, or oversized batches reject the request; service-account and reserved IDs are reported per entry while valid entries save together. A timeout or failed response can follow a committed write: inspect the current limits before retrying. ```bash curl -X PUT 'https://api.factory.ai/api/v0/organization/usage/limits/shared' \ -H 'Authorization: Bearer $FACTORY_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ ... }' ``` **Request body** (optional) ```json { "type": "object", "properties": { "principals": { "type": "array", "items": { "type": "object", "properties": { "principalId": { "type": "string", "minLength": 1, "maxLength": 256 }, "limit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "nullable": true } }, "required": [ "principalId", "limit" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "principals" ], "additionalProperties": false } ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "updated": { "type": "array", "items": { "type": "object", "properties": { "principalId": { "type": "string" }, "limit": { "type": "number", "nullable": true } }, "required": [ "principalId", "limit" ], "additionalProperties": false } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "principalId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "principalId", "error" ], "additionalProperties": false } } }, "required": [ "updated", "errors" ], "additionalProperties": false } ``` **Response:** `400` - Response for status 400 ```json { "anyOf": [ { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" }, "message": { "not": {} } }, "required": [ "detail", "status", "title" ], "additionalProperties": false }, { "type": "object", "properties": { "message": { "type": "string", "description": "Request validation error" }, "errors": { "type": "array", "items": {}, "description": "Framework validation issues, when available" } }, "required": [ "message" ], "additionalProperties": false } ] } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `404` - Response for status 404 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `429` - Response for status 429 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `503` - Response for status 503 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Get user credits limits `GET /api/v0/organization/usage/limits/users` Returns the global per-user credits limit and any individual user overrides for the organization. ```bash curl 'https://api.factory.ai/api/v0/organization/usage/limits/users' \ -H 'Authorization: Bearer $FACTORY_API_KEY' ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "globalLimit": { "type": "integer", "minimum": 0, "nullable": true, "description": "Global per-user credits limit applied to all users without an individual override" }, "userLimits": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "description": "User email address" }, "limit": { "type": "integer", "minimum": 0, "nullable": true, "description": "Individual credits limit override, or null if using the global default" } }, "required": [ "email", "limit" ], "additionalProperties": false }, "description": "Users with individual limit overrides" } }, "required": [ "globalLimit", "userLimits" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Set user credits limits `PUT /api/v0/organization/usage/limits/users` Set individual per-user credits limits for one or more users. Supports bulk updates (up to 100 users per request). Identify each user by email. Pass null for limit to remove an individual override. ```bash curl -X PUT 'https://api.factory.ai/api/v0/organization/usage/limits/users' \ -H 'Authorization: Bearer $FACTORY_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ ... }' ``` **Request body** (optional) ```json { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "description": "User email address" }, "limit": { "type": "integer", "minimum": 1000000, "nullable": true, "description": "Credits limit to set for this user (minimum 1,000,000). Pass null to remove the individual override." } }, "required": [ "email", "limit" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100, "description": "Array of user limit entries (up to 100). Each identifies a user by email." } }, "required": [ "users" ], "additionalProperties": false } ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "updated": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "description": "User email address" }, "limit": { "type": "integer", "minimum": 0, "nullable": true, "description": "The limit that was set, or null if the override was removed" } }, "required": [ "email", "limit" ], "additionalProperties": false }, "description": "Successfully updated user limits" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email that was provided" }, "error": { "type": "string", "description": "Error message" } }, "required": [ "email", "error" ], "additionalProperties": false }, "description": "Errors for users that could not be updated" } }, "required": [ "updated", "errors" ], "additionalProperties": false } ``` **Response:** `400` - Response for status 400 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## List organization users `GET /api/v0/organization/users` Returns a paginated list of users in the Factory organization. ```bash curl 'https://api.factory.ai/api/v0/organization/users' \ -H 'Authorization: Bearer $FACTORY_API_KEY' ``` **Parameters** - `limit` (`string`) - Query parameter. Maximum number of items to return (1-100) - `cursor` (`string`) - Query parameter. Cursor for pagination **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "WorkOS user ID" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "description": "User first name" }, "lastName": { "type": "string", "description": "User last name" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp of user creation" }, "lastSignInAt": { "type": "string", "description": "ISO 8601 timestamp of last sign in" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom metadata for the user" } }, "required": [ "id", "email", "createdAt", "metadata" ], "additionalProperties": false }, "description": "List of users" }, "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether there are more items after this page" }, "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to use for the next page, null if no more pages" } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false } }, "required": [ "users", "pagination" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Remove a user `DELETE /api/v0/organization/users` Removes a user from the organization by email. Works for both active members (deletes membership) and pending invitations (revokes the invite). ```bash curl -X DELETE 'https://api.factory.ai/api/v0/organization/users' \ -H 'Authorization: Bearer $FACTORY_API_KEY' ``` **Parameters** - `email` (`string `, required) - Query parameter. Email address of the user to remove **Response:** `204` - Response for status 204 ```json { "type": "object", "properties": {}, "additionalProperties": false } ``` **Response:** `400` - Response for status 400 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `404` - Response for status 404 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `409` - Response for status 409 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` ## Invite or update a user `POST /api/v0/organization/users/invite` Sends an invitation to a user to join the organization. If the user is already a member, updates their role to the specified value. If the user has a pending invite, returns the current status without changes. If the organization has reached its seat limit, returns status "error" with a descriptive error message. ```bash curl -X POST 'https://api.factory.ai/api/v0/organization/users/invite' \ -H 'Authorization: Bearer $FACTORY_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ ... }' ``` **Request body** (optional) ```json { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address to invite" }, "role": { "type": "string", "enum": [ "user", "manager", "owner" ], "default": "user", "description": "Role to assign (defaults to user)" } }, "required": [ "email" ], "additionalProperties": false } ``` **Response:** `200` - Response for status 200 ```json { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Invited email address" }, "role": { "type": "string", "enum": [ "user", "manager", "owner" ], "description": "Assigned role" }, "status": { "type": "string", "enum": [ "invited", "already_member", "role_updated", "already_invited", "error" ], "description": "Result of the invite operation" }, "error": { "type": "string", "description": "Error message if status is error" } }, "required": [ "email", "role", "status" ], "additionalProperties": false } ``` **Response:** `400` - Response for status 400 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `401` - Response for status 401 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `403` - Response for status 403 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `409` - Response for status 409 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ``` **Response:** `500` - Response for status 500 ```json { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "status": { "type": "number", "description": "HTTP status code" }, "title": { "type": "string", "description": "HTTP status title" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional error metadata" } }, "required": [ "detail", "status", "title" ], "additionalProperties": false } ```