Appwrite Proxy API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Appwrite Proxy API
  description: Appwrite backend as a service cuts up to 70% of the time and costs required for building a modern application. We abstract and simplify common development tasks behind a REST APIs, to help you develop your app in a fast and secure way. For full API documentation and tutorials go to https://appwrite.io/docs
  termsOfService: https://appwrite.io/policy/terms
  contact:
    name: Appwrite Team
    url: https://appwrite.io/support
    email: team@appwrite.io
  license:
    name: BSD-3-Clause
    url: https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE
servers:
- url: https://cloud.appwrite.io/v1
  description: Appwrite Cloud endpoint.
- url: https://{region}.cloud.appwrite.io/v1
  description: Appwrite Cloud regional endpoint. Replace `{region}` with your project region.
  variables:
    region:
      default: fra
      description: Appwrite Cloud region.
tags:
- name: Proxy
  description: The Proxy Service allows you to configure actions for your domains beyond DNS configuration.
paths:
  /proxy/invalidations:
    post:
      summary: Create invalidation
      operationId: proxyCreateInvalidation
      tags:
      - Proxy
      description: 'Create a new CDN cache invalidation for a domain. Executes a hard purge of cached content.


        Depending on type, the invalidation purges a single cache tag, a single URL path, or all cached content for the domain.'
      responses:
        '201':
          description: Invalidation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/proxyInvalidation'
      deprecated: false
      x-appwrite:
        group: null
        demo: proxy/create-invalidation.md
        rate-limit: 60
        rate-time: 60
        rate-key: userId:{userId}, url:{url}
        scope: proxy.invalidations.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  description: Domain name.
                  type: string
                  example: example.com
                type:
                  description: 'Type of reference passed. Allowed values are: tag, path, all'
                  type: string
                  example: tag
                  title: InvalidationType
                  oneOf:
                  - type: string
                    enum:
                    - tag
                    title: tag
                  - type: string
                    enum:
                    - path
                    title: path
                  - type: string
                    enum:
                    - all
                    title: all
                reference:
                  description: 'Reference to invalidate. Depending on type this can be: cache tag name (up to 128 characters), URL path (up to 2048 characters). Not required when type is all.'
                  type: string
                  default: ''
                  example: <REFERENCE>
              required:
              - domain
              - type
  /proxy/rules:
    get:
      summary: List rules
      operationId: proxyListRules
      tags:
      - Proxy
      description: Get a list of all the proxy rules. You can use the query params to filter your results.
      responses:
        '200':
          description: Rule List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/proxyRuleList'
      deprecated: false
      x-appwrite:
        group: rules
        demo: proxy/list-rules.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: rules.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: queries
        description: 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/databases#querying-documents). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: domain, type, trigger, deploymentResourceType, deploymentResourceId, deploymentId, deploymentVcsProviderBranch'
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
      - name: total
        description: When set to false, the total count returned will be 0 and will not be calculated.
        required: false
        schema:
          type: boolean
          example: false
          default: true
        in: query
  /proxy/rules/api:
    post:
      summary: Create API rule
      operationId: proxyCreateAPIRule
      tags:
      - Proxy
      description: 'Create a new proxy rule for serving Appwrite''s API on custom domain.


        Rule ID is automatically generated as MD5 hash of a rule domain for performance purposes.'
      responses:
        '201':
          description: Rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/proxyRule'
      deprecated: false
      x-appwrite:
        group: rules
        demo: proxy/create-api-rule.md
        rate-limit: 10
        rate-time: 60
        rate-key: userId:{userId}, url:{url}
        scope: rules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  description: Domain name.
                  type: string
                  example: example.com
              required:
              - domain
  /proxy/rules/function:
    post:
      summary: Create function rule
      operationId: proxyCreateFunctionRule
      tags:
      - Proxy
      description: 'Create a new proxy rule for executing Appwrite Function on custom domain.


        Rule ID is automatically generated as MD5 hash of a rule domain for performance purposes.'
      responses:
        '201':
          description: Rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/proxyRule'
      deprecated: false
      x-appwrite:
        group: rules
        demo: proxy/create-function-rule.md
        rate-limit: 10
        rate-time: 60
        rate-key: userId:{userId}, url:{url}
        scope: rules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  description: Domain name.
                  type: string
                  example: example.com
                functionId:
                  description: ID of function to be executed.
                  type: string
                  example: <FUNCTION_ID>
                branch:
                  description: Name of VCS branch to deploy changes automatically
                  type: string
                  default: ''
                  example: <BRANCH>
              required:
              - domain
              - functionId
  /proxy/rules/redirect:
    post:
      summary: Create redirect rule
      operationId: proxyCreateRedirectRule
      tags:
      - Proxy
      description: 'Create a new proxy rule for to redirect from custom domain to another domain.


        Rule ID is automatically generated as MD5 hash of a rule domain for performance purposes.'
      responses:
        '201':
          description: Rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/proxyRule'
      deprecated: false
      x-appwrite:
        group: rules
        demo: proxy/create-redirect-rule.md
        rate-limit: 10
        rate-time: 60
        rate-key: userId:{userId}, url:{url}
        scope: rules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  description: Domain name.
                  type: string
                  example: example.com
                url:
                  description: Target URL of redirection
                  type: string
                  example: https://example.com
                  format: url
                statusCode:
                  description: Status code of redirection
                  type: string
                  example: '301'
                  title: StatusCode
                  oneOf:
                  - type: string
                    enum:
                    - '301'
                    title: MovedPermanently
                  - type: string
                    enum:
                    - '302'
                    title: Found
                  - type: string
                    enum:
                    - '307'
                    title: TemporaryRedirect
                  - type: string
                    enum:
                    - '308'
                    title: PermanentRedirect
                resourceId:
                  description: ID of parent resource.
                  type: string
                  example: <RESOURCE_ID>
                resourceType:
                  description: Type of parent resource.
                  type: string
                  example: site
                  title: ProxyResourceType
                  oneOf:
                  - type: string
                    enum:
                    - site
                    title: Site
                  - type: string
                    enum:
                    - function
                    title: Function
              required:
              - domain
              - url
              - statusCode
              - resourceId
              - resourceType
  /proxy/rules/site:
    post:
      summary: Create site rule
      operationId: proxyCreateSiteRule
      tags:
      - Proxy
      description: 'Create a new proxy rule for serving Appwrite Site on custom domain.


        Rule ID is automatically generated as MD5 hash of a rule domain for performance purposes.'
      responses:
        '201':
          description: Rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/proxyRule'
      deprecated: false
      x-appwrite:
        group: rules
        demo: proxy/create-site-rule.md
        rate-limit: 10
        rate-time: 60
        rate-key: userId:{userId}, url:{url}
        scope: rules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  description: Domain name.
                  type: string
                  example: example.com
                siteId:
                  description: ID of site to be executed.
                  type: string
                  example: <SITE_ID>
                branch:
                  description: Name of VCS branch to deploy changes automatically
                  type: string
                  default: ''
                  example: <BRANCH>
              required:
              - domain
              - siteId
  /proxy/rules/{ruleId}:
    get:
      summary: Get rule
      operationId: proxyGetRule
      tags:
      - Proxy
      description: Get a proxy rule by its unique ID.
      responses:
        '200':
          description: Rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/proxyRule'
      deprecated: false
      x-appwrite:
        group: rules
        demo: proxy/get-rule.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: rules.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: ruleId
        description: Rule ID.
        required: true
        schema:
          type: string
          example: <RULE_ID>
        in: path
    delete:
      summary: Delete rule
      operationId: proxyDeleteRule
      tags:
      - Proxy
      description: Delete a proxy rule by its unique ID.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: rules
        demo: proxy/delete-rule.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: rules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: ruleId
        description: Rule ID.
        required: true
        schema:
          type: string
          example: <RULE_ID>
        in: path
  /proxy/rules/{ruleId}/status:
    patch:
      summary: Update rule status
      operationId: proxyUpdateRuleStatus
      tags:
      - Proxy
      description: If not succeeded yet, retry verification process of a proxy rule domain. This endpoint triggers domain verification by checking DNS records. If verification is successful, a TLS certificate will be automatically provisioned for the domain asynchronously in the background.
      responses:
        '200':
          description: Rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/proxyRule'
      deprecated: false
      x-appwrite:
        group: rules
        demo: proxy/update-rule-status.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: rules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: ruleId
        description: Rule ID.
        required: true
        schema:
          type: string
          example: <RULE_ID>
        in: path
components:
  schemas:
    proxyRule:
      description: Rule
      type: object
      properties:
        $id:
          type: string
          description: Rule ID.
          example: 5e5ea5c16897e
        $createdAt:
          type: string
          description: Rule creation date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        $updatedAt:
          type: string
          description: Rule update date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        domain:
          type: string
          description: Domain name.
          example: appwrite.company.com
        type:
          type: string
          description: Action definition for the rule. Possible values are "api", "deployment", or "redirect"
          example: deployment
        trigger:
          type: string
          description: Defines how the rule was created. Possible values are "manual" or "deployment"
          example: manual
        redirectUrl:
          type: string
          description: URL to redirect to. Used if type is "redirect"
          example: https://appwrite.io/docs
        redirectStatusCode:
          type: integer
          description: Status code to apply during redirect. Used if type is "redirect"
          format: int32
          example: 301
        deploymentId:
          type: string
          description: ID of deployment. Used if type is "deployment"
          example: n3u9feiwmf
        deploymentResourceType:
          description: Type of deployment. Possible values are "function", "site". Used if rule's type is "deployment".
          example: function
          type:
          - string
          - 'null'
          oneOf:
          - type: string
            enum:
            - function
            title: function
          - type: string
            enum:
            - site
            title: site
        deploymentResourceId:
          type: string
          description: ID of deployment's resource (site or function ID). Used if type is "deployment"
          example: n3u9feiwmf
        deploymentVcsProviderBranch:
          type: string
          description: Name of Git branch that updates rule. Used if type is "deployment"
          example: main
        status:
          description: Domain verification status. Possible values are "unverified", "verifying", "verified"
          example: verified
          type: string
          oneOf:
          - type: string
            enum:
            - unverified
            title: unverified
          - type: string
            enum:
            - verifying
            title: verifying
          - type: string
            enum:
            - verified
            title: verified
        logs:
          type: string
          description: Logs from rule verification or certificate generation. Certificate generation logs are prioritized if both are available.
          example: Verification of DNS records failed with DNS resolver 8.8.8.8. Domain stage.myapp.com does not have DNS record.
        renewAt:
          type: string
          description: Certificate auto-renewal date in ISO 8601 format.
          example: datetime
      required:
      - $id
      - $createdAt
      - $updatedAt
      - domain
      - type
      - trigger
      - redirectUrl
      - redirectStatusCode
      - deploymentId
      - deploymentResourceId
      - deploymentVcsProviderBranch
      - status
      - logs
      - renewAt
      example:
        $id: 5e5ea5c16897e
        $createdAt: '2020-10-15T06:38:00.000+00:00'
        $updatedAt: '2020-10-15T06:38:00.000+00:00'
        domain: appwrite.company.com
        type: deployment
        trigger: manual
        redirectUrl: https://appwrite.io/docs
        redirectStatusCode: 301
        deploymentId: n3u9feiwmf
        deploymentResourceType: function
        deploymentResourceId: n3u9feiwmf
        deploymentVcsProviderBranch: main
        status: verified
        logs: Verification of DNS records failed with DNS resolver 8.8.8.8. Domain stage.myapp.com does not have DNS record.
        renewAt: datetime
    proxyInvalidation:
      description: Invalidation
      type: object
      properties:
        domain:
          type: string
          description: Domain name.
          example: appwrite.company.com
        type:
          type: string
          description: Invalidation type. Possible values are "tag", "path", or "all".
          example: tag
        reference:
          type: string
          description: Invalidated reference. Depending on type this is a cache tag name, a URL path, or empty when type is all.
          example: products
        status:
          type: string
          description: Invalidation status.
          example: success
      required:
      - domain
      - type
      - reference
      - status
      example:
        domain: appwrite.company.com
        type: tag
        reference: products
        status: success
    proxyRuleList:
      description: Rule List
      type: object
      properties:
        total:
          type: integer
          description: Total number of rules that matched your query.
          format: int32
          example: 5
        rules:
          type: array
          description: List of rules.
          items:
            $ref: '#/components/schemas/proxyRule'
          example: []
      required:
      - total
      - rules
      example:
        total: 5
        rules: ''
  securitySchemes:
    Project:
      type: apiKey
      name: X-Appwrite-Project
      description: Your project ID
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
        demo: <YOUR_PROJECT_ID>
    ProjectPath:
      type: apiKey
      name: project
      description: Your project ID
      in: query
      x-appwrite:
        location: path
        param: project_id
        platforms:
        - client
        - server
        - console
        demo: <YOUR_PROJECT_ID>
    JWT:
      type: apiKey
      name: X-Appwrite-JWT
      description: Your secret JSON Web Token
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
        demo: <YOUR_JWT>
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The OAuth access token to authenticate with
      x-appwrite:
        platforms:
        - client
        - server
        - console
    Locale:
      type: apiKey
      name: X-Appwrite-Locale
      description: ''
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
        demo: en
    Session:
      type: apiKey
      name: X-Appwrite-Session
      description: The user session to authenticate with
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
    DevKey:
      type: apiKey
      name: X-Appwrite-Dev-Key
      description: Your secret dev API key
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
    Cookie:
      type: apiKey
      name: Cookie
      description: The user cookie to authenticate with. Used by SDKs that forward an incoming Cookie header in server-side runtimes.
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
    ImpersonateUserId:
      type: apiKey
      name: X-Appwrite-Impersonate-User-Id
      description: Impersonate a user by ID
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
    ImpersonateUserEmail:
      type: apiKey
      name: X-Appwrite-Impersonate-User-Email
      description: Impersonate a user by email
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
    ImpersonateUserPhone:
      type: apiKey
      name: X-Appwrite-Impersonate-User-Phone
      description: Impersonate a user by phone
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
    Key:
      type: apiKey
      name: X-Appwrite-Key
      description: Your secret API key
      in: header
      x-appwrite:
        platforms:
        - server
        - console
        - manager
        demo: <YOUR_API_KEY>
    Organization:
      type: apiKey
      name: X-Appwrite-Organization
      description: Your organization ID
      in: header
      x-appwrite:
        platforms:
        - server
        - console
        demo: <YOUR_ORGANIZATION_ID>
    ForwardedUserAgent:
      type: apiKey
      name: X-Forwarded-User-Agent
      description: The user agent string of the client that made the request
      in: header
      x-appwrite:
        platforms:
        - server
    Mode:
      type: apiKey
      name: X-Appwrite-Mode
      description: ''
      in: header
      x-appwrite:
        platforms:
        - console
        demo: ''
    Platform:
      type: apiKey
      name: X-Appwrite-Platform
      description: The platform type (Appwrite or Imagine)
      in: header
      x-appwrite:
        platforms:
        - console
externalDocs:
  description: Full API docs, specs and tutorials
  url: https://appwrite.io/docs