> ## Documentation Index > Fetch the complete documentation index at: https://docs.membrane.agency/llms.txt > Use this file to discover all available pages before exploring further. # create-action > Create a new action for a connection or integration. Returns the created action object including its ID. ## OpenAPI ````yaml /api-reference/membrane-api.json post /actions openapi: 3.0.0 info: title: Membrane API description: API documentation for Membrane Engine version: '1.0' contact: {} servers: - url: https://api.getmembrane.com security: - bearer: [] tags: [] paths: /actions: post: summary: create-action description: >- Create a new action for a connection or integration. Returns the created action object including its ID. operationId: createAction requestBody: required: true content: application/json: schema: type: object properties: key: description: >- Stable key for referencing the element (e.g. in selectors). Unique per (parent, integration) scope. Generated from name if not provided on create. type: string name: description: >- Display name. Optional on create; used to generate key when key is omitted. type: string description: description: Optional human-readable description. type: string type: type: string description: >- Determines which handler runs and which config schema is used for validation (e.g. "run-javascript", "api-request-to-external-app"). inputSchema: description: >- JSON Schema for the action input. Used by the action engine for template output schema, run-time variables, and output mapping. type: object additionalProperties: {} config: type: object additionalProperties: {} description: >- Type-specific configuration object. Validated by the handler's config schema; passed to handler setup/run and getTemplateOutputSchema. For type "run-javascript", config.code uses this contract: action.run-javascript: input { input: unknown, user: unknown, connection: { id: string, name: string }, integration: { id: string, key?: string, name?: string } | undefined } + custom-code runtime clients -> unknown. Full contract: doc:functions/action-run-javascript. connectionId: description: >- Connection ID for filtering or for connection-level instances. Same semantics as base integration-level property. type: string integrationId: description: >- Internal ID of the integration this element belongs to. Omit for universal elements; set for integration-specific elements. Uniqueness of key is scoped per integration. type: string required: - name - type - config additionalProperties: false responses: '200': description: >- Create a new action for a connection or integration. Returns the created action object including its ID. content: application/json: schema: type: object properties: id: type: string description: >- Internal database ID of the element. Assigned by the API; unique per element. name: type: string description: >- Display name. Always present in API responses (filled by API if not set on create). uuid: description: >- Stable unique identifier (UUID). Can be provided on create; otherwise generated. Must be unique across elements of this type. type: string key: description: >- Stable key for referencing the element (e.g. in selectors). Unique per (parent, integration) scope. Generated from name if not provided on create. type: string description: description: Optional human-readable description. type: string meta: description: Optional key-value metadata. type: object additionalProperties: {} state: description: >- Current lifecycle or health state (e.g. READY, SETUP_FAILED, CONFIGURATION_ERROR, BUILDING). Set by the engine during setup and validation. type: string enum: - BUILDING - CLIENT_ACTION_REQUIRED - CONFIGURATION_ERROR - SETUP_FAILED - READY - DISCONNECTING errors: description: Validation or setup errors when state is not READY. type: array items: type: object revision: description: >- Opaque revision token; changes on each update. Used for optimistic concurrency. type: string createdAt: description: ISO date when the element was created. type: string updatedAt: description: ISO date when the element was last updated. type: string archivedAt: description: >- When set, the element is archived (soft-deleted). Archived elements cannot be patched. type: string isDeactivated: description: >- When true, setup is skipped and the element is treated as inactive (e.g. when dependencies are deactivated or the element is archived). type: boolean isReadOnly: description: >- When true, the element cannot be modified (e.g. published package elements or elements from another workspace). type: boolean integrationId: description: >- Internal ID of the integration this element belongs to. Omit for universal elements; set for integration-specific elements. Uniqueness of key is scoped per integration. type: string integrationUuid: description: >- UUID of the integration; alternative to integrationId when creating from export. Resolved to integrationId by the API. type: string integrationKey: description: >- Key of the integration; alternative to integrationId. Resolved to integrationId by the API. type: string parentId: description: >- Internal ID of the parent workspace element. Used for hierarchy (e.g. integration-level under universal). Child key uniqueness is scoped by parent and integration. type: string parentUuid: description: >- UUID of the parent element; alternative to parentId when creating (e.g. from export). Resolved to parentId by the API. type: string parentKey: description: >- Key of the parent element; alternative to parentId. Resolved to parentId by the API. type: string connectionId: description: >- Connection ID for filtering or for connection-level instances. Same semantics as base integration-level property. type: string instanceKey: description: >- Key for the connection-level instance when multiple exist per connection. Same semantics as base integration-level property. type: string isUniversal: description: >- When true, the element is universal (shared across all integrations). Requires universal-element access. Omit or false for integration-specific elements. type: boolean externalAppId: description: >- Internal ID of the external app this element belongs to. Auto-populated from the integration when integrationId is set and the integration has an externalAppId. type: string externalAppUuid: description: >- UUID of the external app when this action is published in a package that has an external app. Populated in API responses for published actions. type: string externalAppKey: description: >- Key of the external app; alternative to externalAppId. Resolved to externalAppId by the API. type: string inputSchema: description: >- JSON Schema for the action input. Used by the action engine for template output schema, run-time variables, and output mapping. allOf: - type: object type: description: >- Action type (e.g. HttpRequest, RunJavascript). Determines which handler runs and which config schema is used for validation. type: string enum: - api-request-to-external-app - api-request-to-your-app - http-request - run-javascript - api-request config: description: >- Type-specific configuration object. Validated by the handler's config schema; passed to handler setup/run and getTemplateOutputSchema. type: object properties: {} additionalProperties: {} outputMapping: description: >- Mapping expression to transform the action's raw output. Evaluated with access to input, output, and user; used to compute transformed output schema and at run time. customOutputSchema: description: >- Explicit output schema for the action. Takes precedence over the transformed or default output schema when resolving outputSchema. allOf: - type: object isCustomized: type: boolean userId: type: string tenantId: type: string ownerName: type: string nullable: true agentSessionId: description: >- [INTERNAL] ID of the agent session building this action. Present when the action was created or updated with an intent. type: string universalParentId: description: >- For connection-level instances: ID of the universal (root) action in the hierarchy. Set automatically when creating an instance; used in list/selector queries to filter by universal parent. type: string outputSchema: allOf: - type: object isPublic: description: >- When true, the element is publicly listed (e.g. in universe). Used for published packages; publish/unpublish updates this on published elements. type: boolean logoUri: description: >- Resolved app logo for this element (integration -> connector -> external app -> favicon). type: string appliedToIntegrations: type: array items: type: object properties: element: type: object properties: id: type: string description: >- Internal database ID of the element. Assigned by the API; unique per element. name: type: string description: >- Display name. Always present in API responses (filled by API if not set on create). uuid: description: >- Stable unique identifier (UUID). Can be provided on create; otherwise generated. Must be unique across elements of this type. type: string key: description: >- Stable key for referencing the element (e.g. in selectors). Unique per (parent, integration) scope. Generated from name if not provided on create. type: string description: description: Optional human-readable description. type: string meta: description: Optional key-value metadata. type: object additionalProperties: {} state: description: >- Current lifecycle or health state (e.g. READY, SETUP_FAILED, CONFIGURATION_ERROR, BUILDING). Set by the engine during setup and validation. type: string enum: - BUILDING - CLIENT_ACTION_REQUIRED - CONFIGURATION_ERROR - SETUP_FAILED - READY - DISCONNECTING errors: description: >- Validation or setup errors when state is not READY. type: array items: type: object revision: description: >- Opaque revision token; changes on each update. Used for optimistic concurrency. type: string createdAt: description: ISO date when the element was created. type: string updatedAt: description: ISO date when the element was last updated. type: string archivedAt: description: >- When set, the element is archived (soft-deleted). Archived elements cannot be patched. type: string isDeactivated: description: >- When true, setup is skipped and the element is treated as inactive (e.g. when dependencies are deactivated or the element is archived). type: boolean isReadOnly: description: >- When true, the element cannot be modified (e.g. published package elements or elements from another workspace). type: boolean integrationId: description: >- Internal ID of the integration this element belongs to. Omit for universal elements; set for integration-specific elements. Uniqueness of key is scoped per integration. type: string integrationUuid: description: >- UUID of the integration; alternative to integrationId when creating from export. Resolved to integrationId by the API. type: string integrationKey: description: >- Key of the integration; alternative to integrationId. Resolved to integrationId by the API. type: string parentId: description: >- Internal ID of the parent workspace element. Used for hierarchy (e.g. integration-level under universal). Child key uniqueness is scoped by parent and integration. type: string parentUuid: description: >- UUID of the parent element; alternative to parentId when creating (e.g. from export). Resolved to parentId by the API. type: string parentKey: description: >- Key of the parent element; alternative to parentId. Resolved to parentId by the API. type: string connectionId: description: >- Connection ID for filtering or for connection-level instances. Same semantics as base integration-level property. type: string instanceKey: description: >- Key for the connection-level instance when multiple exist per connection. Same semantics as base integration-level property. type: string isUniversal: description: >- When true, the element is universal (shared across all integrations). Requires universal-element access. Omit or false for integration-specific elements. type: boolean externalAppId: description: >- Internal ID of the external app this element belongs to. Auto-populated from the integration when integrationId is set and the integration has an externalAppId. type: string externalAppUuid: description: >- UUID of the external app when this action is published in a package that has an external app. Populated in API responses for published actions. type: string externalAppKey: description: >- Key of the external app; alternative to externalAppId. Resolved to externalAppId by the API. type: string inputSchema: description: >- JSON Schema for the action input. Used by the action engine for template output schema, run-time variables, and output mapping. allOf: - type: object type: description: >- Action type (e.g. HttpRequest, RunJavascript). Determines which handler runs and which config schema is used for validation. type: string enum: - api-request-to-external-app - api-request-to-your-app - http-request - run-javascript - api-request config: description: >- Type-specific configuration object. Validated by the handler's config schema; passed to handler setup/run and getTemplateOutputSchema. type: object properties: {} additionalProperties: {} outputMapping: description: >- Mapping expression to transform the action's raw output. Evaluated with access to input, output, and user; used to compute transformed output schema and at run time. customOutputSchema: description: >- Explicit output schema for the action. Takes precedence over the transformed or default output schema when resolving outputSchema. allOf: - type: object isCustomized: type: boolean userId: type: string tenantId: type: string ownerName: type: string nullable: true agentSessionId: description: >- [INTERNAL] ID of the agent session building this action. Present when the action was created or updated with an intent. type: string universalParentId: description: >- For connection-level instances: ID of the universal (root) action in the hierarchy. Set automatically when creating an instance; used in list/selector queries to filter by universal parent. type: string outputSchema: description: >- Resolved output schema (cached after setup). Derived from customOutputSchema, transformed schema from outputMapping, default output schema, or parent custom output schema. Read-only. isPublic: description: >- When true, the element is publicly listed (e.g. in universe). Used for published packages; publish/unpublish updates this on published elements. type: boolean required: - id - name additionalProperties: false integrationId: type: string required: - element - integrationId additionalProperties: false defaultOutputSchema: allOf: - type: object transformedOutputSchema: allOf: - type: object dependencies: type: array items: {} required: - id - name additionalProperties: false components: securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http ````