Skip to content

Commit f8189ac

Browse files
pinkeshmarspinkeshmars
committed
Project APIs Docs
1 parent 01fce3b commit f8189ac

File tree

1 file changed

+384
-0
lines changed

1 file changed

+384
-0
lines changed

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

Lines changed: 384 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,384 @@
1+
---
2+
slug: project-apis
3+
title: Project APIs
4+
tags: [APIs, Projects]
5+
keywords: [projects, apis, refactor code]
6+
sidebar_position: 5
7+
---
8+
9+
# Project API
10+
11+
The FlutterFlow **Project APIs** allow you to programmatically read, write, and validate YAML configuration files through REST endpoints. Using these APIs, you can automate project management tasks, integrate continuous integration and delivery (CI/CD) workflows, and apply bulk configuration updates without manual interactions with the FlutterFlow user interface.
12+
13+
:::warning
14+
15+
The Project API is currently in beta and may undergo changes that could affect functionality or compatibility.
16+
17+
:::
18+
19+
:::info[Prerequisites]
20+
21+
Before using the Project YAML API, make sure you have the following:
22+
23+
- **HTTP Client**: Use a tool like `curl`, [**Postman**](https://www.postman.com/), or an HTTP library in your preferred programming language (e.g., `axios`, `requests`).
24+
- **Project Access**: You must have read access for GET/validation operations and an editor access for making updates to the project.
25+
- **Paid Plan**: You need a paid [**FlutterFlow subscription plan**](https://www.flutterflow.io/pricing).
26+
27+
:::
28+
29+
## Base URL
30+
31+
FlutterFlow provides different API endpoints for various environments. Use the appropriate base URL below depending on your needs:
32+
33+
#### Production:
34+
```jsx
35+
https://api.flutterflow.io/v2/
36+
```
37+
#### Beta/Staging:
38+
```jsx
39+
https://api.flutterflow.io/v2-staging/
40+
```
41+
42+
#### Enterprise:
43+
- India: `https://api-enterprise-india.flutterflow.io/v2/`
44+
- APAC: `https://api-enterprise-apac.flutterflow.io/v2/`
45+
- US Central: `https://api-enterprise-us-central.flutterflow.io/v2/`
46+
- Europe: `https://api-enterprise-europe.flutterflow.io/v2/`
47+
48+
## Authentication
49+
50+
All API endpoints require authentication using a Bearer token. You'll need to include your FlutterFlow API token in the Authorization header of each request. See [how to get the API Token](../../../accounts-billing/account-management.md#how-do-i-generate-an-api-token).
51+
52+
```jsx
53+
Authorization: Bearer YOUR_API_TOKEN_HERE
54+
```
55+
56+
## API Endpoints
57+
Below is a list of available API endpoints with their methods and usage descriptions.
58+
59+
| Endpoint | Method | Purpose |
60+
| --------------------------- | ------ | --------------------------------------------- |
61+
| `/listPartitionedFileNames` | GET | List available YAML file names for a project |
62+
| `/projectYamls` | GET | Export/download YAML files from a project |
63+
| `/validateProjectYaml` | POST | Validate YAML content before applying changes |
64+
| `/updateProjectYaml` | POST | Update project configuration via YAML |
65+
66+
67+
### List File Names
68+
69+
Before you read or update project files, you need to know what YAML files are available. This endpoint returns a full list of file names associated with your FlutterFlow project.
70+
71+
#### Endpoint
72+
`GET /listPartitionedFileNames`
73+
74+
#### Query Parameters
75+
`projectId` (required): The ID of the FlutterFlow project
76+
77+
#### Response
78+
```jsx
79+
{
80+
"success":true,
81+
"reason":null,
82+
"value":{
83+
"versionInfo": {
84+
"partitionerVersion": 6,
85+
"projectSchemaFingerprint": "abc123"
86+
},
87+
"fileNames": [
88+
"folders",
89+
"app-details",
90+
"collections/id-yr7z6g5a",
91+
"page/id-Scaffold_l9g6ilb6/page-widget-tree-outline/node/id-Column_174wuhc4",
92+
"custom-file/id-MAIN/custom-file-code",
93+
...
94+
]
95+
}
96+
}
97+
```
98+
99+
#### Example Usage
100+
```jsx
101+
curl -X GET \
102+
'https://api.flutterflow.io/v2/listPartitionedFileNames?projectId=your-project-id' \
103+
-H 'Authorization: Bearer YOUR_API_TOKEN'
104+
```
105+
106+
107+
108+
### Download Project YAML
109+
110+
You can download specific or all YAML configuration files from your FlutterFlow project. This helps in understanding the current structure of the file before modifying it.
111+
112+
#### Endpoint
113+
`GET /projectYamls`
114+
115+
#### Query Parameters
116+
- `projectId` (required): The ID of the FlutterFlow project
117+
- `fileName` (optional): Specific file to export (without extension). If not provided, all files are exported.
118+
119+
#### Response
120+
Returns a zip file encoded as a base64 string. You will need to manually decode this base64 data into a downloadable .zip file. To do so, copy the value of `projectYamlBytes` and then you can use online tools such as [base64.guru](https://base64.guru/converter/decode/file) or [b64encode.com](https://b64encode.com/tools/base64-to-zip/) to convert and download the files.
121+
122+
```jsx
123+
{
124+
"success":true,
125+
"reason":null,
126+
"value":{
127+
"versionInfo": {
128+
"partitionerVersion": 6,
129+
"projectSchemaFingerprint": "abc123"
130+
},
131+
"projectYamlBytes": "UEsDBAoAAAAAAKxV..."
132+
}
133+
}
134+
```
135+
136+
#### Example Usage
137+
```jsx
138+
# Export all YAML files
139+
curl -X GET \
140+
'https://api.flutterflow.io/v2/projectYamls?projectId=your-project-id' \
141+
-H 'Authorization: Bearer YOUR_API_TOKEN'
142+
143+
# Export specific file
144+
curl -X GET \
145+
'https://api.flutterflow.io/v2/projectYamls?projectId=your-project-id&fileName=ad-mob' \
146+
-H 'Authorization: Bearer YOUR_API_TOKEN'
147+
```
148+
149+
### Validate Project YAML
150+
151+
You must validate the YAML content before applying changes to ensure it's properly formatted and contains valid values.
152+
153+
#### Endpoint
154+
`POST /validateProjectYaml`
155+
156+
#### Request Body
157+
```jsx
158+
{
159+
"projectId": "your-project-id",
160+
"fileKey": "ad-mob",
161+
"fileContent": "showTestAds: false\nappId: \"your-app-id\""
162+
}
163+
```
164+
165+
:::info
166+
167+
- In the `fileContent` object, you must provide the **entire content** of the file.
168+
- 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 ❌.
169+
170+
```jsx
171+
{
172+
"projectId": "ecommerce-flow-app-ie7nl6",
173+
"fileKey": "app-state",
174+
"fileContent": "fields:
175+
- parameter:
176+
identifier:
177+
name: myAppState
178+
key: hg7j8z0y
179+
dataType:
180+
scalarType: String
181+
description: "Stores the current user session state"
182+
persisted: false"
183+
}
184+
```
185+
186+
Now, here’s how the YAML content should be passed (i.e., as single line string ✅).
187+
188+
```jsx
189+
{
190+
"projectId": "ecommerce-flow-app-ie7nl6",
191+
"fileKey": "app-state",
192+
"fileContent": "fields:\n - parameter:\n identifier:\n name: myAppState\n key: hg7j8z0y\n dataType:\n scalarType: String\n description: \"Stores the current user session state\"\n persisted: false"
193+
}
194+
```
195+
196+
:::
197+
198+
#### Response
199+
- **Success (200):** YAML is valid - `{"success": true, "reason": null, "value": ""}`
200+
- **Error with validation details:**
201+
```jsx
202+
{
203+
"validationErrors": [
204+
{
205+
"message": "Expected bool value",
206+
"fileKey": "ad-mob",
207+
"yamlLocation": {
208+
"line": 1,
209+
"column": 15
210+
}
211+
}
212+
]
213+
}
214+
```
215+
216+
#### Example Usage
217+
```jsx
218+
curl -X POST \
219+
'https://api.flutterflow.io/v2/validateProjectYaml' \
220+
-H 'Authorization: Bearer YOUR_API_KEY' \
221+
-H 'Content-Type: application/json' \
222+
-d '{
223+
"projectId": "your-project-id",
224+
"fileKey": "ad-mob",
225+
"fileContent": "showTestAds: false"
226+
}'
227+
```
228+
229+
230+
### Update Project YAML
231+
232+
This endpoint allows you to overwrite existing files in your FlutterFlow project by submitting updated YAML content.
233+
234+
#### Endpoint
235+
`POST /updateProjectYaml`
236+
237+
#### Request Body
238+
```jsx
239+
{
240+
"projectId": "your-project-id",
241+
"fileKeyToContent": {
242+
"ad-mob": "showTestAds: false",
243+
}
244+
}
245+
```
246+
:::info
247+
- In the `fileKeyToContent` object, you must provide the **entire content** of the file.
248+
- The YAML content must be passed as a **single-line string** with correct formatting and appropriate escaping for newlines and indentation. For example, in the `fileKeyToContent` object, you see the actual multiline YAML content, which is not allowed ❌.
249+
250+
```jsx
251+
{
252+
"projectId": "ecommerce-flow-app-ie7nl6",
253+
"fileKeyToContent": {
254+
"app-state": "fields:
255+
- parameter:
256+
identifier:
257+
name: myAppState
258+
key: hg7j8z0y
259+
dataType:
260+
scalarType: String
261+
description: "Stores the current user session state"
262+
persisted: false"
263+
}
264+
}
265+
```
266+
Now, here’s how the YAML content should be passed (i.e., as single line string ✅).
267+
```jsx
268+
{
269+
"projectId": "ecommerce-flow-app-ie7nl6",
270+
"fileKeyToContent": {
271+
"app-state": "fields:\n - parameter:\n identifier:\n name: myAppState\n key: hg7j8z0y\n dataType:\n scalarType: String\n description: \"Stores the current user session state\"\n persisted: false"
272+
}
273+
}
274+
```
275+
276+
:::
277+
278+
#### Response
279+
- **Success (200):** `{"success": true, "reason": null, "value": ""}`
280+
- **Error (400):** Validation errors or malformed request.
281+
- **Error (403):** Insufficient permissions or project locked.
282+
- **Error (404):** Project or user not found.
283+
284+
#### Example Usage
285+
286+
This example updates the `ad-mob` file and adds/updates app state variables.
287+
288+
```jsx
289+
curl -X POST \
290+
'https://api.flutterflow.io/v2/updateProjectYaml' \
291+
-H 'Authorization: Bearer YOUR_API_TOKEN' \
292+
-H 'Content-Type: application/json' \
293+
-d '{
294+
"projectId": "your-project-id",
295+
"fileKeyToContent": {
296+
"ad-mob": "showTestAds: false",
297+
"app-state": "fields:\n - parameter:\n identifier:\n name: myAppState\n key: hg7j8z0y\n dataType:\n scalarType: String\n description: \"Stores the current user session state\"\n persisted: false\n - parameter:\n identifier:\n name: userPreferences\n key: abc123xy\n dataType:\n scalarType: JSON\n description: \"User settings and preferences\"\n persisted: true"
298+
}
299+
}'
300+
```
301+
## API Usage Example
302+
303+
Let’s walk through a practical example of updating an app state variable using the Project APIs.
304+
305+
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/).
306+
307+
![image]
308+
309+
Next, we open the `app-state.yaml` file and update the `enableDarkMode` variable by setting its `persisted` value to `true`. We then convert the updated YAML into a properly escaped single line string and validate it using the `/validateProjectYaml` endpoint. If validation succeeds, we send the final update using the `/updateProjectYaml` endpoint.
310+
311+
![image]
312+
313+
## Error Handling
314+
This section outlines how the API handles errors, including common HTTP response codes and detailed validation feedback for YAML processing issues.
315+
316+
### Common Error Responses
317+
This table outlines the most common HTTP status codes and their meanings, helping you identify and resolve API issues more effectively.
318+
319+
| Status Code | Description | Example Response |
320+
| ----------- | -------------------------------------------- | -------------------------------------------------------- |
321+
| 400 | Bad Request - Invalid JSON or malformed YAML | `"Failed to update project: ad-mob:Expected bool value"` |
322+
| 403 | Forbidden - Insufficient permissions | `"You do not have write access to this project"` |
323+
| 404 | Not Found - Project or user doesn't exist | `"Project not found"` |
324+
| 500 | Internal Server Error | `"Unknown error"` |
325+
326+
### Validation Errors
327+
When YAML validation fails, you'll receive detailed error information:
328+
329+
```jsx
330+
{
331+
"validationErrors": [
332+
{
333+
"message": "Unknown field name 'showTestAdsasssdaf'",
334+
"fileKey": "ad-mob",
335+
"yamlLocation": {
336+
"line": 1,
337+
"column": 1
338+
}
339+
}
340+
]
341+
}
342+
```
343+
344+
345+
## Best Practices
346+
347+
- **Always Validate First**: Before updating project YAMLs, use the validation endpoint to ensure your changes are valid:
348+
349+
```jsx
350+
# 1. Validate the YAML
351+
curl -X POST 'https://api.flutterflow.io/v2/validateProjectYaml' \
352+
-H 'Authorization: Bearer YOUR_API_KEY' \
353+
-H 'Content-Type: application/json' \
354+
-d '{"projectId": "project-id", "fileKey": "ad-mob", "fileContent": "showTestAds: false"}'
355+
356+
# 2. If validation passes, apply the changes
357+
curl -X POST 'https://api.flutterflow.io/v2/updateProjectYaml' \
358+
-H 'Authorization: Bearer YOUR_API_KEY' \
359+
-H 'Content-Type: application/json' \
360+
-d '{"projectId": "project-id", "fileKeyToContent": {"ad-mob": "showTestAds: false"}}'
361+
```
362+
363+
364+
- **Handle Project Locks**: Projects may be temporarily locked during other operations. If you receive a 403 error mentioning `Project is locked due to ongoing changes. Please try again later.`, wait and retry.
365+
366+
- **Batch Updates**: You can update multiple files in a single request by including multiple entries in `fileKeyToContent`:
367+
368+
```jsx
369+
{
370+
"projectId": "your-project-id",
371+
"fileKeyToContent": {
372+
"ad-mob": "showTestAds: false",
373+
"app-settings": "appName: \"Updated Name\"",
374+
"authentication": "enableEmailAuth: true"
375+
}
376+
}
377+
```
378+
379+
380+
## Rate Limits
381+
382+
Please be mindful of API rate limits. If you're making many requests, implement appropriate delays between calls to avoid being rate-limited.
383+
384+

0 commit comments

Comments
 (0)