Go to Console
Star on GitHub 45.1K Get started

Functions

SERVER

The Functions service allows you to create custom behaviour that can be triggered by any supported Appwrite system events or by a predefined schedule.

Appwrite Cloud Functions lets you automatically run backend code in response to events triggered by Appwrite or by setting it to be executed in a predefined schedule. Your code is stored in a secure way on your Appwrite instance and is executed in an isolated environment.

You can learn more by following our Cloud Functions tutorial.

Base URL
https://cloud.appwrite.io/v1

List Functions

Get a list of all the project's functions. You can use the query params to filter your results.

  • Request
    • search string

      Search term to filter your list results. Max length: 256 chars.

    • limit integer

      Maximum number of functions to return in response. By default will return maximum 25 results. Maximum of 100 results allowed per request.

    • cursor string

      ID of the function used as the starting point for the query, excluding the function itself. Should be used for efficient pagination when working with large sets of data. learn more about pagination

    • cursorDirection string

      Direction of the cursor, can be either 'before' or 'after'.

    • orderType string

      Order result by ASC or DESC order.

  • Response
Endpoint
GET /functions
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.list()

puts response.inspect

Create Function

Create a new function. You can pass a list of permissions to allow different project users or team with access to execute the function using the client API.

  • Request
    • functionId string
      required

      Function ID. Choose your own unique ID or pass the string "unique()" to auto generate it. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

    • name string
      required

      Function name. Max length: 128 chars.

    • execute array
      required

      An array of strings with execution permissions. By default no user is granted with any execute permissions. learn more about permissions and get a full list of available permissions. Maximum of 100 scopes are allowed, each 64 characters long.

    • runtime string
      required

      Execution runtime.

    • vars object

      Key-value JSON object that will be passed to the function as environment variables.

    • events array

      Events list. Maximum of 100 events are allowed.

    • schedule string

      Schedule CRON syntax.

    • timeout integer

      Function maximum execution time in seconds.

  • Response
Endpoint
POST /functions
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.create(function_id: '[FUNCTION_ID]', name: '[NAME]', execute: ["role:all"], runtime: 'node-14.5')

puts response.inspect

List runtimes

Get a list of all runtimes that are currently active on your instance.

Endpoint
GET /functions/runtimes
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.list_runtimes()

puts response.inspect

Get Function

Get a function by its unique ID.

  • Request
    • functionId string
      required

      Function ID.

  • Response
Endpoint
GET /functions/{functionId}
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.get(function_id: '[FUNCTION_ID]')

puts response.inspect

Update Function

Update function by its unique ID.

  • Request
    • functionId string
      required

      Function ID.

    • name string
      required

      Function name. Max length: 128 chars.

    • execute array
      required

      An array of strings with execution permissions. By default no user is granted with any execute permissions. learn more about permissions and get a full list of available permissions. Maximum of 100 scopes are allowed, each 64 characters long.

    • vars object

      Key-value JSON object that will be passed to the function as environment variables.

    • events array

      Events list. Maximum of 100 events are allowed.

    • schedule string

      Schedule CRON syntax.

    • timeout integer

      Maximum execution time in seconds.

  • Response
Endpoint
PUT /functions/{functionId}
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.update(function_id: '[FUNCTION_ID]', name: '[NAME]', execute: ["role:all"])

puts response.inspect

Delete Function

Delete a function by its unique ID.

  • Request
    • functionId string
      required

      Function ID.

  • Response
    • 204 application/json
Endpoint
DELETE /functions/{functionId}
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.delete(function_id: '[FUNCTION_ID]')

puts response.inspect

List Deployments

Get a list of all the project's code deployments. You can use the query params to filter your results.

  • Request
    • functionId string
      required

      Function ID.

    • search string

      Search term to filter your list results. Max length: 256 chars.

    • limit integer

      Maximum number of deployments to return in response. By default will return maximum 25 results. Maximum of 100 results allowed per request.

    • cursor string

      ID of the deployment used as the starting point for the query, excluding the deployment itself. Should be used for efficient pagination when working with large sets of data. learn more about pagination

    • cursorDirection string

      Direction of the cursor, can be either 'before' or 'after'.

    • orderType string

      Order result by ASC or DESC order.

  • Response
Endpoint
GET /functions/{functionId}/deployments
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.list_deployments(function_id: '[FUNCTION_ID]')

puts response.inspect

Create Deployment

Create a new function code deployment. Use this endpoint to upload a new version of your code function. To execute your newly uploaded code, you'll need to update the function's deployment to use your new deployment UID.

This endpoint accepts a tar.gz file compressed with your code. Make sure to include any dependencies your code has within the compressed file. You can learn more about code packaging in the Appwrite Cloud Functions tutorial.

Use the "command" param to set the entry point used to execute your code.

  • Request
    • functionId string
      required

      Function ID.

    • entrypoint string
      required

      Entrypoint File.

    • code string
      required

      Gzip file with your code package. When used with the Appwrite CLI, pass the path to your code directory, and the CLI will automatically package your code. Use a path that is within the current directory.

    • activate boolean
      required

      Automatically activate the deployment when it is finished building.

  • Response
Endpoint
POST /functions/{functionId}/deployments
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.create_deployment(function_id: '[FUNCTION_ID]', entrypoint: '[ENTRYPOINT]', code: Appwrite::InputFile.from_path('dir/file.png'), activate: false)

puts response.inspect

Get Deployment

Get a code deployment by its unique ID.

  • Request
    • functionId string
      required

      Function ID.

    • deploymentId string
      required

      Deployment ID.

  • Response
Endpoint
GET /functions/{functionId}/deployments/{deploymentId}
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.get_deployment(function_id: '[FUNCTION_ID]', deployment_id: '[DEPLOYMENT_ID]')

puts response.inspect

Update Function Deployment

Update the function code deployment ID using the unique function ID. Use this endpoint to switch the code deployment that should be executed by the execution endpoint.

  • Request
    • functionId string
      required

      Function ID.

    • deploymentId string
      required

      Deployment ID.

  • Response
Endpoint
PATCH /functions/{functionId}/deployments/{deploymentId}
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.update_deployment(function_id: '[FUNCTION_ID]', deployment_id: '[DEPLOYMENT_ID]')

puts response.inspect

Delete Deployment

Delete a code deployment by its unique ID.

  • Request
    • functionId string
      required

      Function ID.

    • deploymentId string
      required

      Deployment ID.

  • Response
    • 204 application/json
Endpoint
DELETE /functions/{functionId}/deployments/{deploymentId}
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.delete_deployment(function_id: '[FUNCTION_ID]', deployment_id: '[DEPLOYMENT_ID]')

puts response.inspect

Retry Build

  • Request
    • functionId string
      required

      Function ID.

    • deploymentId string
      required

      Deployment ID.

    • buildId string
      required

      Build unique ID.

  • Response
    • 204 application/json
Endpoint
POST /functions/{functionId}/deployments/{deploymentId}/builds/{buildId}
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.retry_build(function_id: '[FUNCTION_ID]', deployment_id: '[DEPLOYMENT_ID]', build_id: '[BUILD_ID]')

puts response.inspect

List Executions

Get a list of all the current user function execution logs. You can use the query params to filter your results. On admin mode, this endpoint will return a list of all of the project's executions. Learn more about different API modes.

  • Request
    • functionId string
      required

      Function ID.

    • limit integer

      Maximum number of executions to return in response. By default will return maximum 25 results. Maximum of 100 results allowed per request.

    • search string

      Search term to filter your list results. Max length: 256 chars.

    • cursor string

      ID of the execution used as the starting point for the query, excluding the execution itself. Should be used for efficient pagination when working with large sets of data. learn more about pagination

    • cursorDirection string

      Direction of the cursor, can be either 'before' or 'after'.

  • Response
Endpoint
GET /functions/{functionId}/executions
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.list_executions(function_id: '[FUNCTION_ID]')

puts response.inspect

Create Execution

Trigger a function execution. The returned object will return you the current execution status. You can ping the Get Execution endpoint to get updates on the current execution status. Once this endpoint is called, your function execution process will start asynchronously.

  • Request
    • functionId string
      required

      Function ID.

    • data string

      String of custom data to send to function.

    • async boolean

      Execute code asynchronously. Default value is true.

  • Response
  • Rate limits

    This endpoint is not limited when using Server SDKs with API keys. If you are using SSR with setSession, these rate limits will still apply. Learn more about SSR rate limits.

    The limit is applied for each unique limit key.

    Time frame
    Attempts
    Key
    1 minutes 60 requests URL + IP
Endpoint
POST /functions/{functionId}/executions
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.create_execution(function_id: '[FUNCTION_ID]')

puts response.inspect

Get Execution

Get a function execution log by its unique ID.

  • Request
    • functionId string
      required

      Function ID.

    • executionId string
      required

      Execution ID.

  • Response
Endpoint
GET /functions/{functionId}/executions/{executionId}
Ruby
require 'appwrite'

client = Appwrite::Client.new

client
    .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
    .set_project('5df5acd0d48c2') # Your project ID
    .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key

functions = Appwrite::Functions.new(client)

response = functions.get_execution(function_id: '[FUNCTION_ID]', execution_id: '[EXECUTION_ID]')

puts response.inspect
Copyright © 2024 Appwrite