> ## Documentation Index
> Fetch the complete documentation index at: https://formcarry.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List forms

> Returns the forms your key can access, newest first, each with its full configuration.



## OpenAPI

````yaml https://api.formcarry.com/docs-json get /v1/forms
openapi: 3.0.0
info:
  title: formcarry API
  description: >-
    Welcome to the formcarry API.


    Authenticate every request with an API key from your team's API page in the
    dashboard, sent as `Authorization: Bearer fc_live_...`.

    Requests and responses are JSON.


    Lists are paginated with a cursor: pass a response's `next_cursor` as
    `cursor` to get the next page, until `next_cursor` is null.


    Errors return a `code` you can act on and a `message` you can show. Every
    response includes an `X-Request-Id` header; quote it when you contact
    support.
  version: '1'
  contact: {}
servers:
  - url: https://api.formcarry.com
security: []
tags:
  - name: forms
    description: Your forms
  - name: submissions
    description: Submissions received by a form
  - name: me
    description: The key you are using
  - name: health
    description: Service status
paths:
  /v1/forms:
    get:
      tags:
        - forms
      summary: List forms
      description: >-
        Returns the forms your key can access, newest first, each with its full
        configuration.
      operationId: FormsController_list
      parameters:
        - name: limit
          required: false
          in: query
          description: Results per page.
          schema:
            minimum: 1
            maximum: 100
            default: 25
            type: number
        - name: cursor
          required: false
          in: query
          description: The next_cursor value from the previous page.
          schema:
            type: string
        - name: team_id
          required: false
          in: query
          description: >-
            Only this team (must be one the credential covers). Useful for
            connections that span several teams.
          example: 64b000000000000000000001
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormList'
        '401':
          description: The request carried no usable key or token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                missing_bearer:
                  summary: missing_bearer
                  value:
                    error:
                      type: authentication_error
                      code: missing_bearer
                      message: >-
                        Send your key as "Authorization: Bearer fc_live_..." on
                        every request.
                      request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a
                invalid_key:
                  summary: invalid_key
                  value:
                    error:
                      type: authentication_error
                      code: invalid_key
                      message: >-
                        This API key or access token is unknown, revoked or
                        expired.
                      request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a
                wrong_audience:
                  summary: wrong_audience
                  value:
                    error:
                      type: authentication_error
                      code: wrong_audience
                      message: >-
                        This access token was issued for a different resource.
                        Authorize again for this server.
                      request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a
        '403':
          description: The key is valid but may not do this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                insufficient_scope:
                  summary: insufficient_scope
                  value:
                    error:
                      type: permission_error
                      code: insufficient_scope
                      message: This key is missing the submissions:write scope.
                      required:
                        - submissions:write
                      request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a
                form_access_restricted:
                  summary: form_access_restricted
                  value:
                    error:
                      type: permission_error
                      code: form_access_restricted
                      message: >-
                        This key is restricted to specific forms and cannot
                        create new ones.
                      request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a
                team_inactive:
                  summary: team_inactive
                  value:
                    error:
                      type: permission_error
                      code: team_inactive
                      message: The team that owns this key is not active.
                      request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a
                owner_unverified:
                  summary: owner_unverified
                  value:
                    error:
                      type: permission_error
                      code: owner_unverified
                      message: >-
                        The team owner must verify their email address before
                        the API can be used.
                      request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a
        '429':
          description: Slow down and retry after the Retry-After header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                rate_limited:
                  summary: rate_limited
                  value:
                    error:
                      type: rate_limit_error
                      code: rate_limited
                      message: Too many requests.
                      request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a
                scan_concurrency:
                  summary: scan_concurrency
                  value:
                    error:
                      type: rate_limit_error
                      code: scan_concurrency
                      message: >-
                        At most 2 filtered submission requests may run at once
                        per key. Wait for the running ones to finish.
                      request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a
      security:
        - api_key: []
components:
  schemas:
    FormList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FormResource'
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true
      required:
        - data
        - has_more
        - next_cursor
    ErrorEnvelope:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
        - error
    FormResource:
      type: object
      properties:
        id:
          type: string
          example: AbC123xyz
          readOnly: true
        team_id:
          type: string
          readOnly: true
        name:
          type: string
          example: Contact form
        endpoint:
          type: string
          example: https://formcarry.com/s/AbC123xyz
          readOnly: true
          description: Where your HTML form posts.
        active:
          type: boolean
          description: Inactive forms reject submissions.
        avatar:
          type: string
          example: 🚀
          readOnly: true
        folder_id:
          type: string
          nullable: true
          description: The folder the form is filed in, or null for none.
        created_at:
          type: string
          example: '2026-01-15T10:00:00.000Z'
          readOnly: true
        last_submission_at:
          type: string
          nullable: true
          readOnly: true
          description: When the newest submission arrived, or null before the first.
        submissions:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/SubmissionCounts'
        storage:
          $ref: '#/components/schemas/StorageBlock'
        spam:
          $ref: '#/components/schemas/SpamBlock'
        self_email_notification:
          $ref: '#/components/schemas/SelfEmailNotificationBlock'
        auto_response:
          $ref: '#/components/schemas/AutoResponseBlock'
        after_submit:
          $ref: '#/components/schemas/AfterSubmitBlock'
        webhooks:
          readOnly: true
          description: Managed at /v1/forms/{form_id}/webhooks; one per form for now.
          type: array
          items:
            $ref: '#/components/schemas/WebhookResource'
        validation:
          $ref: '#/components/schemas/ValidationBlock'
      required:
        - id
        - team_id
        - name
        - endpoint
        - active
        - avatar
        - folder_id
        - created_at
        - last_submission_at
        - submissions
        - storage
        - spam
        - self_email_notification
        - auto_response
        - after_submit
        - webhooks
        - validation
    ErrorBody:
      type: object
      properties:
        type:
          type: string
          enum:
            - authentication_error
            - permission_error
            - invalid_request_error
            - rate_limit_error
            - api_error
          example: invalid_request_error
        code:
          type: string
          example: invalid_parameter
        message:
          type: string
          example: limit must not be greater than 100
        param:
          type: string
          description: The offending parameter, when there is one
          example: limit
        required:
          description: >-
            On insufficient_scope: the scopes the request needs. Reissue the key
            with them.
          example:
            - submissions:write
          type: array
          items:
            type: string
        retry_after:
          type: number
          description: 'On scan_concurrency: seconds to wait before trying again.'
          example: 2
        request_id:
          type: string
          description: Echoes X-Request-Id. Quote it when contacting support.
          example: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a
      required:
        - type
        - code
        - message
        - request_id
    SubmissionCounts:
      type: object
      properties:
        this_month:
          type: number
          description: Submissions received this calendar month.
        all_time:
          type: number
          nullable: true
          description: Submissions received since the form was created.
      required:
        - this_month
        - all_time
    StorageBlock:
      type: object
      properties:
        store_submissions:
          type: boolean
          description: >-
            When false, submissions are forwarded by email and webhook but
            nothing is stored.
        keep_for:
          type: string
          enum:
            - 30_days
            - 60_days
            - 90_days
            - 180_days
            - 365_days
            - forever
          description: How long stored submissions are kept before they are removed.
    SpamBlock:
      type: object
      properties:
        protection:
          type: boolean
          description: formcarry's built-in spam filter.
        captcha:
          $ref: '#/components/schemas/CaptchaBlock'
    SelfEmailNotificationBlock:
      type: object
      properties:
        enabled:
          type: boolean
          description: Send an email to the recipients on every submission.
        recipients:
          description: >-
            Who receives the email. Replaces the whole list. The free plan
            allows one address.
          example:
            - me@company.com
          type: array
          items:
            type: string
        include_spam:
          type: boolean
          description: Also send the email for submissions the spam filter flagged.
        subject:
          type: string
          nullable: true
          maxLength: 256
          description: Email subject. null uses formcarry's default.
        logo_url:
          type: string
          nullable: true
          maxLength: 2048
          description: >-
            The logo of the email, shown by the built-in themes and available to
            a custom template. Upload one with the images endpoint (use
            `self_email_notification_logo`) or use any public PNG, JPEG or GIF
            URL.
          example: https://example.com/logo.png
        logo_height:
          type: number
          nullable: true
          minimum: 16
          maximum: 400
          description: Logo height in pixels. null lets the template decide.
        template:
          $ref: '#/components/schemas/SelfEmailNotificationTemplateBlock'
        sender:
          $ref: '#/components/schemas/SenderBlock'
    AutoResponseBlock:
      type: object
      properties:
        enabled:
          type: boolean
          description: >-
            Send a reply to the person who submitted the form (their email field
            is used as the address).
        subject:
          type: string
          nullable: true
          maxLength: 256
          description: Subject of the reply.
        from_name:
          type: string
          nullable: true
          maxLength: 128
          description: The name the reply appears to come from.
        logo_url:
          type: string
          nullable: true
          maxLength: 2048
          description: >-
            The logo of the reply, shown by the built-in themes and available to
            a custom template. Upload one with the images endpoint (use
            `auto_response_logo`) or use any public PNG, JPEG or GIF URL.
          example: https://example.com/logo.png
        logo_height:
          type: number
          nullable: true
          minimum: 16
          maximum: 400
          description: Logo height in pixels. null lets the template decide.
        template:
          $ref: '#/components/schemas/AutoResponseTemplateBlock'
    AfterSubmitBlock:
      type: object
      properties:
        type:
          type: string
          enum:
            - formcarry_page
            - redirect
          description: >-
            formcarry_page: show formcarry's thank you page. redirect: send the
            visitor to your own URL.
        page:
          $ref: '#/components/schemas/AfterSubmitPageBlock'
        redirect:
          $ref: '#/components/schemas/AfterSubmitRedirectBlock'
    WebhookResource:
      type: object
      properties:
        id:
          type: string
          example: whk_3f9Kq2bLm8xZpQ1rT7vWc0
          readOnly: true
        url:
          type: string
          example: https://example.com/hooks/formcarry
        enabled:
          type: boolean
        description:
          type: string
          nullable: true
          example: CRM sync
        events:
          example:
            - submission.created
          type: array
          items:
            type: string
        signing:
          description: >-
            How deliveries are signed: an HMAC-SHA256 of "<timestamp>.<raw
            body>" with the secret, sent as "t=<unix seconds>,v1=<hex>" in this
            header. Recompute it over the raw body you received, compare in
            constant time, and refuse a timestamp older than a few minutes.
            Retries are signed again with a fresh timestamp.
          allOf:
            - $ref: '#/components/schemas/WebhookSigning'
        last_delivery:
          nullable: true
          readOnly: true
          description: >-
            Always null: the delivery log is the record, at GET
            .../webhooks/{webhook_id}/deliveries.
          allOf:
            - $ref: '#/components/schemas/WebhookLastDelivery'
        created_at:
          type: string
          example: '2026-09-13T12:00:00.000Z'
          readOnly: true
      required:
        - id
        - url
        - enabled
        - description
        - events
        - signing
        - last_delivery
        - created_at
    ValidationBlock:
      type: object
      properties:
        enabled:
          type: boolean
          description: Reject submissions that fail the rules.
        rules:
          description: Replaces the whole list.
          type: array
          items:
            $ref: '#/components/schemas/ValidationRule'
    CaptchaBlock:
      type: object
      properties:
        provider:
          type: string
          enum:
            - none
            - recaptcha
            - hcaptcha
            - turnstile
          description: >-
            Which captcha your form embeds. formcarry verifies the response with
            this secret key.
        secret_key:
          type: string
          nullable: true
          maxLength: 512
          description: >-
            The secret key from your captcha provider's dashboard. Write only: a
            read carries secret_key_set instead, and null on a write keeps the
            stored one. To drop it, set the provider to none.
          writeOnly: true
        secret_key_set:
          type: boolean
          readOnly: true
          description: >-
            Whether a secret key is stored. Read only: ignored on a write, so a
            form read and sent back whole is fine.
    SelfEmailNotificationTemplateBlock:
      type: object
      properties:
        type:
          type: string
          enum:
            - formcarry
            - custom
          description: >-
            formcarry: one of the built-in themes. custom: your own template,
            sent in `html`. A custom template is not plain HTML: it is a
            Mustache template that formcarry fills in for every submission. See
            the documentation on custom email templates for how it works.
        theme:
          type: string
          enum:
            - formal
            - fancy
          description: The built-in theme, used when type is formcarry.
        html:
          type: string
          nullable: true
          maxLength: 200000
          description: >-
            Your own template, used when type is custom. Not plain HTML: a
            Mustache template with tags such as {{email}} that formcarry fills
            in for every submission. See the documentation on custom email
            templates for the tags and the rules.
    SenderBlock:
      type: object
      properties:
        type:
          type: string
          enum:
            - formcarry
            - email_server
            - premium_server
          description: >-
            formcarry: sent from formcarry. email_server: one of your own SMTP
            servers. premium_server: one of your verified sending domains.
        server_id:
          type: string
          nullable: true
          maxLength: 64
          description: >-
            The id of the server, from GET /v1/email-servers. Required for
            email_server and premium_server, null for formcarry.
        name:
          type: string
          nullable: true
          maxLength: 128
          description: Sender name, premium_server only. Null for the other types.
        email:
          type: string
          nullable: true
          maxLength: 320
          description: >-
            Sender address, premium_server only. Must belong to the verified
            domain. Null for the other types.
    AutoResponseTemplateBlock:
      type: object
      properties:
        type:
          type: string
          enum:
            - formcarry
            - custom
          description: >-
            formcarry: one of the built-in themes with your message. custom:
            your own template, sent in `html`. A custom template is not plain
            HTML: it is a Mustache template that formcarry fills in for every
            submission. See the documentation on custom email templates for how
            it works.
        theme:
          type: string
          enum:
            - formal
            - fancy
          description: The built-in theme, used when type is formcarry.
        message:
          type: string
          nullable: true
          maxLength: 20000
          description: The message body, used when type is formcarry.
        html:
          type: string
          nullable: true
          maxLength: 200000
          description: >-
            Your own template, used when type is custom. Not plain HTML: a
            Mustache template with tags such as {{email}} that formcarry fills
            in for every submission. See the documentation on custom email
            templates for the tags and the rules.
    AfterSubmitPageBlock:
      type: object
      properties:
        theme:
          type: string
          enum:
            - sweet
            - fancy
            - formal
        mode:
          type: string
          enum:
            - light
            - dark
            - system
          description: Light or dark colours, or follow the visitor's system setting.
        headline:
          type: string
          nullable: true
          maxLength: 256
          description: The page title.
          example: Thank you!
        message:
          type: string
          nullable: true
          maxLength: 2000
          description: The text under the title.
          example: We have received your submission
        logo_url:
          type: string
          nullable: true
          maxLength: 2048
          description: Logo for the light look.
          example: https://example.com/thanks
        logo_dark_url:
          type: string
          nullable: true
          maxLength: 2048
          description: Logo for the dark look.
          example: https://example.com/thanks
        logo_size:
          type: string
          enum:
            - normal
            - big
        primary_color:
          type: string
          nullable: true
          maxLength: 32
          description: A CSS colour.
          example: '#0f766e'
        secondary_color:
          type: string
          nullable: true
          maxLength: 32
          description: A CSS colour.
          example: '#f0fdfa'
        return_button:
          description: The button that sends the visitor back to your site.
          allOf:
            - $ref: '#/components/schemas/PageButtonBlock'
        download_button:
          description: An optional second button, for example to a file.
          allOf:
            - $ref: '#/components/schemas/PageButtonBlock'
    AfterSubmitRedirectBlock:
      type: object
      properties:
        success_url:
          type: string
          nullable: true
          maxLength: 2048
          description: Where the visitor goes after a successful submission.
          example: https://example.com/thanks
        fail_url:
          type: string
          nullable: true
          maxLength: 2048
          description: >-
            Where the visitor goes when the submission is rejected. null uses
            success_url.
          example: https://example.com/thanks
        append_submission_to_url:
          type: boolean
          description: Append the submitted fields to the redirect URL as query parameters.
    WebhookSigning:
      type: object
      properties:
        algorithm:
          type: string
          example: hmac-sha256
        header:
          type: string
          example: X-Formcarry-Signature
      required:
        - algorithm
        - header
    WebhookLastDelivery:
      type: object
      properties:
        at:
          type: string
          example: '2026-09-13T12:00:00.000Z'
        status:
          type: string
          enum:
            - succeeded
            - failed
        response_status:
          type: number
          nullable: true
          example: 200
        attempt:
          type: number
          example: 1
      required:
        - at
        - status
        - response_status
        - attempt
    ValidationRule:
      type: object
      properties:
        field:
          type: string
          maxLength: 128
          description: The name of the field in your HTML form.
          example: email
        checks:
          type: array
          items:
            $ref: '#/components/schemas/ValidationCheck'
      required:
        - field
        - checks
    PageButtonBlock:
      type: object
      properties:
        text:
          type: string
          nullable: true
          maxLength: 64
          description: Button label. null hides the button.
        url:
          type: string
          nullable: true
          maxLength: 2048
          description: Where the button leads.
          example: https://example.com/thanks
    ValidationCheck:
      type: object
      properties:
        type:
          type: string
          enum:
            - required
            - email
            - url
            - phone_number
            - integer
            - min_length
            - max_length
            - contains
            - not_contains
        value:
          type: string
          nullable: true
          maxLength: 256
          description: The argument for min_length, max_length, contains and not_contains.
        message:
          type: string
          nullable: true
          maxLength: 512
          description: Replaces the default error message shown to the visitor.
      required:
        - type
  securitySchemes:
    api_key:
      scheme: bearer
      bearerFormat: fc_live_...
      type: http

````

## Related topics

- [List a form's fields](/docs/api-reference/forms/list-a-forms-fields.md)
- [List webhooks](/docs/api-reference/forms/list-webhooks.md)
- [List submissions](/docs/api-reference/submissions/list-submissions.md)
- [List deliveries](/docs/api-reference/forms/list-deliveries.md)
- [List email servers](/docs/api-reference/forms/list-email-servers.md)