Project APIs Docs #390

pinkeshmars · 2025-06-11T10:27:52Z

Description

Project APIs Docs

Linear ticket and magic word Fixes DEVR-XXX

Type of change

bolt-new-by-stackblitz · 2025-06-11T10:27:55Z

Run & review this pull request in StackBlitz Codeflow.

michael-mcroskey

Lgtm with some minor comments!

Just thinking for the future, it would be great to build out our API documentation more heavily (since there are like 10+ endpoints actually available!). Will follow up later with thoughts!

michael-mcroskey · 2025-06-11T14:01:56Z

docs/resources/projects/settings/project-apis.md

+
+FlutterFlow provides different API endpoints for various environments. Use the appropriate base URL below depending on your needs:
+
+#### Production:


Nit: possible to put these (including enterprise) in tabs?

michael-mcroskey · 2025-06-11T14:07:50Z

docs/resources/projects/settings/project-apis.md

+- **Paid Plan**: You need a paid [**FlutterFlow subscription plan**](https://www.flutterflow.io/pricing).
+
+:::
+


It might make sense to do a brief overview of what the YAML represents. Feel free to add/remove/tweak portions, but basically a "what/why" before getting into the "how"

## Background ### What are FlutterFlow Project YAMLs? YAML (YAML Ain't Markup Language) is a human-readable data serialization format commonly used for configuration files. In FlutterFlow, **Project YAMLs represent the complete structural definition of your app** — essentially exposing the full project schema that powers your FlutterFlow application. ### What's Included in the Project Schema? FlutterFlow's YAML files contain a comprehensive representation of your entire project, including: - **UI Components & Pages**: Widget trees, page layouts, component hierarchies, and styling configurations - **App Configuration**: Settings like app details, authentication methods, integrations (AdMob, Firebase, etc.) - **Data Structures**: Database collections, API schemas, app state variables, and custom data types - **Business Logic**: Actions, functions, conditional logic, and workflow definitions - **Assets & Resources**: Custom code files, images references, fonts, and other project assets - **Project Organization**: Folder structures, component libraries, and project metadata ### YAML vs. FlutterFlow UI Every change you make in the FlutterFlow visual editor — from dragging a widget onto a page to configuring a database collection — is ultimately stored as structured data in these YAML files. The FlutterFlow UI provides an intuitive visual interface for editing this underlying schema, while the Project API gives you direct programmatic access to the same data. ### File Structure FlutterFlow automatically partitions your project into logical YAML files for optimal performance and organization. Each file represents a specific aspect of your project (e.g., `app-state`, `ad-mob`, individual pages, collections, etc.), making it easy to target specific updates without affecting the entire project.

LGTM, just changed the title 'Background' to 'YAML Overview'

michael-mcroskey · 2025-06-11T14:14:36Z

docs/resources/projects/settings/project-apis.md

+
+### Validate Project YAML
+
+You must validate the YAML content before applying changes to ensure it's properly formatted and contains valid values.


@victoriahuang1 if a user does not validate the YAML content before attempting a change, will it always fail?

No. But validating will ensure that your YAML can be accepted

michael-mcroskey · 2025-06-11T14:15:36Z

docs/resources/projects/settings/project-apis.md

+:::info
+
+- In the `fileContent` object, you must provide the **entire content** of the file.
+- The YAML content must be passed as a **single-line string** with correct formatting and appropriate escaping for new lines and indentation. For example, in the `fileContent` object, you see the actual multiline YAML content, which is not allowed ❌.


Nit: "For example, in the following fileContent object..."

michael-mcroskey · 2025-06-11T14:18:09Z

docs/resources/projects/settings/project-apis.md

+
+Let’s walk through a practical example of updating an app state variable using the Project APIs.
+
+First, we use the `/listPartitionedFileNames` endpoint to check if the `app-state` file exists in the project. Once confirmed, we call the `/projectYamls` endpoint to download the YAML file. The API returns a base64-encoded string representing a zip file, which we decode and download using tools like [Base64 to ZIP](https://b64encode.com/tools/base64-to-zip/).


Our of curiosity, if it doesn't exist, does making the same call create it?

You can create new files when uploading file contents via the update endpoint

michael-mcroskey · 2025-06-11T14:20:48Z

docs/resources/projects/settings/project-apis.md

+
+## Rate Limits
+
+Please be mindful of API rate limits. If you're making many requests, implement appropriate delays between calls to avoid being rate-limited.


@victoriahuang1 can you confirm if there are rate limits? If so, it would be great to document them explicitly.

@michael-mcroskey they will be forwarded to our default API rate limits. Lmk if you want us to set custom rate limits for these specific endpoints

rule { action = "throttle" preview = false # Should have lower priority than the other API methods. priority = 999 description = "other API methods" match { expr { expression = "!request.path.contains(\"/cf/\")" } } rate_limit_options { ban_duration_sec = 0 conform_action = "allow" enforce_on_key = "HTTP_HEADER" # Header name with auth token enforce_on_key_name = "authorization" exceed_action = "deny(429)" rate_limit_threshold { count = 30 interval_sec = 300 } } }

victoriahuang1 · 2025-06-11T20:17:29Z

docs/resources/projects/settings/project-apis.md

+    "versionInfo": {
+      "partitionerVersion": 6,
+      "projectSchemaFingerprint": "abc123"
+    },


explain that this should be used for api versioning

@victoriahuang1 I didn't get this! Could you please elaborate on this? How can it be used for api versioning?

This is how our APIs are versioned -- this is the version info.
If any part of this changes, that means that our API has been updated and the format of our responses has changed

Done! added.

victoriahuang1 · 2025-06-11T20:17:56Z

docs/resources/projects/settings/project-apis.md

+
+### Validate Project YAML
+
+You must validate the YAML content before applying changes to ensure it's properly formatted and contains valid values.


No. But validating will ensure that your YAML can be accepted

victoriahuang1 · 2025-06-11T20:19:35Z

docs/resources/projects/settings/project-apis.md

+
+Let’s walk through a practical example of updating an app state variable using the Project APIs.
+
+First, we use the `/listPartitionedFileNames` endpoint to check if the `app-state` file exists in the project. Once confirmed, we call the `/projectYamls` endpoint to download the YAML file. The API returns a base64-encoded string representing a zip file, which we decode and download using tools like [Base64 to ZIP](https://b64encode.com/tools/base64-to-zip/).


You can create new files when uploading file contents via the update endpoint

victoriahuang1 · 2025-06-11T20:20:52Z

docs/resources/projects/settings/project-apis.md

+
+## Rate Limits
+
+Please be mindful of API rate limits. If you're making many requests, implement appropriate delays between calls to avoid being rate-limited.


@michael-mcroskey they will be forwarded to our default API rate limits. Lmk if you want us to set custom rate limits for these specific endpoints

rule { action = "throttle" preview = false # Should have lower priority than the other API methods. priority = 999 description = "other API methods" match { expr { expression = "!request.path.contains(\"/cf/\")" } } rate_limit_options { ban_duration_sec = 0 conform_action = "allow" enforce_on_key = "HTTP_HEADER" # Header name with auth token enforce_on_key_name = "authorization" exceed_action = "deny(429)" rate_limit_threshold { count = 30 interval_sec = 300 } } }

Project APIs Docs

f8189ac

pinkeshmars requested review from victoriahuang1 and michael-mcroskey June 11, 2025 10:27

michael-mcroskey approved these changes Jun 11, 2025

View reviewed changes

victoriahuang1 reviewed Jun 11, 2025

View reviewed changes

pinkeshmars and others added 4 commits June 12, 2025 11:07

Address review comments

513c292

Merge branch 'main' into feature/project-apis

8f0aa9c

Address review comments

9afd483

Merge branch 'main' into feature/project-apis

c4d639b


		FlutterFlow provides different API endpoints for various environments. Use the appropriate base URL below depending on your needs:

		#### Production:

		- Paid Plan: You need a paid [FlutterFlow subscription plan](https://www.flutterflow.io/pricing).

		:::


		### Validate Project YAML

		You must validate the YAML content before applying changes to ensure it's properly formatted and contains valid values.


		Let’s walk through a practical example of updating an app state variable using the Project APIs.

		First, we use the `/listPartitionedFileNames` endpoint to check if the `app-state` file exists in the project. Once confirmed, we call the `/projectYamls` endpoint to download the YAML file. The API returns a base64-encoded string representing a zip file, which we decode and download using tools like [Base64 to ZIP](https://b64encode.com/tools/base64-to-zip/).


		## Rate Limits

		Please be mindful of API rate limits. If you're making many requests, implement appropriate delays between calls to avoid being rate-limited.

Project APIs Docs #390

Are you sure you want to change the base?

Project APIs Docs #390

Conversation

pinkeshmars commented Jun 11, 2025

Description

Type of change

Uh oh!

bolt-new-by-stackblitz bot commented Jun 11, 2025

Uh oh!

michael-mcroskey left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!