# Foleon API The Foleon API enables you to quickly and easily develop functional applications or integrations. In fact, this is the same API that powers the Foleon platform itself. The API follows RESTful principles, so if you've worked with a RESTful API before, many of its concepts will be familiar to you. It leverages standard HTTP features, making it compatible with most HTTP clients. Most responses, including errors, are returned in JSON format. Designed for clarity and ease of use, the API adheres to standard HTTP response codes, providing detailed error messages when necessary. Version: 1.0.0 License: Proprietary ## Servers EU cluster ``` https://api.foleon.com ``` US cluster ``` https://api.us.foleon.com ``` ## Security ### BearerAuth Type: http Scheme: bearer ## Download OpenAPI description [Foleon API](https://developers.foleon.com/_bundle/apis/index.yaml) ## Authentication Authenticate your requests using your api credentials by creating a bearer token. ### Obtain an OAuth token - [POST /oauth](https://developers.foleon.com/apis/authentication/obtainoauthtoken.md): Use your credentials to obtain a token to authenticate your subsequent requests. ## Docs All endpoints related to creating, retrieving or deleting Docs (editions), or updating their settings. ### Retrieve a Doc - [GET /v2/magazine/edition/{doc_id}](https://developers.foleon.com/apis/docs/getdocbyid.md): Get a Doc resource by it's ID. ### Update a Doc - [PATCH /v2/magazine/edition/{doc_id}](https://developers.foleon.com/apis/docs/patchdocbyid.md): Update a Doc's properties and settings, such as the remarketing code, or utm code. ### Delete a Doc - [DELETE /v2/magazine/edition/{doc_id}](https://developers.foleon.com/apis/docs/deletedocbyid.md): WARNING: Deleting a Doc is permanent and cannot be undone. Using this endpoint is risky. Consider unpublishing your Doc instead. ### List Docs - [GET /v2/magazine/edition](https://developers.foleon.com/apis/docs/listdocs.md): Query all jobs available in your scope to return a list of Docs. Use bracket notation in the parameters to filter and order the data. ### Create a Doc - [POST /v2/magazine/edition](https://developers.foleon.com/apis/docs/createdoc.md): Create a new Doc in an existing project (title). ### Copy a Doc - [POST /v3/magazine/edition/{doc_id}/copy](https://developers.foleon.com/apis/docs/copydoc.md): Copy a Doc into an existing project (title) ### Publish a Doc - [POST /magazine/edition/{doc_id}/publish](https://developers.foleon.com/apis/docs/publishdoc.md): Publish or Re-Publish a Doc. ### Export a Doc as a tar.gz webpackage - [POST /magazine/edition/{doc_id}/tar](https://developers.foleon.com/apis/docs/creategzippeddoc.md): Triggers an export for a webpackage of the Doc, containing the raw HTML and Javascript to host the Doc on your own server. It can take up to 30 minutes for the export to complete. Use the /documents endpoint to query the media library for the created export. ## Projects All endpoints related to Projects (titles). ### Retrieve a Project - [GET /v2/magazine/title/{project_id}](https://developers.foleon.com/apis/projects/getprojectbyid.md): Get a Project resource by it's ID. ### Update a Project - [PATCH /v2/magazine/title/{project_id}](https://developers.foleon.com/apis/projects/patchprojectbyid.md): Update a project's settings, such as your CRM set up, or your hostname. ### Delete a Project - [DELETE /v2/magazine/title/{project_id}](https://developers.foleon.com/apis/projects/deleteprojectbyid.md): WARNING: Deleting a Project is permanent and cannot be undone. Using this endpoint is risky. ### List Projects - [GET /v2/magazine/title](https://developers.foleon.com/apis/projects/listprojects.md): Query all projects available in your scope to return a list of Projects. Use bracket notation in the parameters to filter and order the data. ### Create a Project - [POST /v2/magazine/title](https://developers.foleon.com/apis/projects/createproject.md): Create a new project, select a workspace (account) to put the project into by providing the workspace id. ## Users All endpoints related to Users. ### Retrieve a User - [GET /v2/user/{user_id}](https://developers.foleon.com/apis/users/getuserbyid.md): Get a User resource by it's ID. ### Update a User - [PATCH /v2/user/{user_id}](https://developers.foleon.com/apis/users/patchuserbyid.md): Update a User's settings. ### Delete a User - [DELETE /v2/user/{user_id}](https://developers.foleon.com/apis/users/deleteuserbyid.md): WARNING: Deleting a User is permanent and cannot be undone. Using this endpoint is risky. ### List Users - [GET /v2/user](https://developers.foleon.com/apis/users/listusers.md): Query all Users available in your scope to return a list of Users. Use bracket notation in the parameters to filter and order the data. ### Create a User - [POST /v2/user](https://developers.foleon.com/apis/users/createuser.md): Create a new User, select a Workspace (account) for the User by providing the Workspace ID. ## Workspaces All endpoints related to Workspaces (accounts). ### Retrieve a Workspace - [GET /v2/account/{workspace_id}](https://developers.foleon.com/apis/workspaces/getworkspacebyid.md): Get a Workspace resource by it's ID. ### Update a Workspace - [PATCH /v2/account/{workspace_id}](https://developers.foleon.com/apis/workspaces/patchworkspacebyid.md): Update a Workspace's settings. ### Delete a Workspace - [DELETE /v2/account/{workspace_id}](https://developers.foleon.com/apis/workspaces/deleteworkspacebyid.md): WARNING: Deleting a Workspace is permanent and cannot be undone. Using this endpoint is risky. ### List Workspaces - [GET /v2/account](https://developers.foleon.com/apis/workspaces/listworkspaces.md): Query all Workspaces available in your scope to return a list of Workspaces. Use bracket notation in the parameters to filter and order the data. ### Create a Workspace - [POST /v2/account](https://developers.foleon.com/apis/workspaces/createworkspace.md): Create a new Workspace. ## Personalization Categories All endpoints related to Personalization Categories. ### Retrieve a Personalization Category - [GET /personalization/category/{category_id}](https://developers.foleon.com/apis/personalization-categories/getpersonalizationcategorybyid.md): Get a Personalization Category resource by it's ID. ### Update a Personalization Category - [PATCH /personalization/category/{category_id}](https://developers.foleon.com/apis/personalization-categories/patchpersonalizationcategorybyid.md): Update a Personalization Category's settings. ### Delete a Personalization Category - [DELETE /personalization/category/{category_id}](https://developers.foleon.com/apis/personalization-categories/deletepersonalizationcategorybyid.md): WARNING: Deleting a Personalization Category is permanent and cannot be undone. Using this endpoint is risky. ### List Personalization Categories - [GET /personalization/category](https://developers.foleon.com/apis/personalization-categories/listpersonalizationcategories.md): Query all Personalization Categories available in your scope to return a list of Personalization Categories. Use bracket notation in the parameters to filter and order the data. ### Create a Personalization Category - [POST /personalization/category](https://developers.foleon.com/apis/personalization-categories/createpersonalizationcategory.md): Create a new Personalization Category. ## Personalization Options All endpoints related to Personalization Options. ### Retrieve a Personalization Option - [GET /personalization/property/option/{option_id}](https://developers.foleon.com/apis/personalization-options/getpersonalizationoptionbyid.md): Get a Personalization Option resource by it's ID. ### Update a Personalization Option - [PATCH /personalization/property/option/{option_id}](https://developers.foleon.com/apis/personalization-options/patchpersonalizationoptionbyid.md): Update a Personalization Option's settings. ### Delete a Personalization Option - [DELETE /personalization/property/option/{option_id}](https://developers.foleon.com/apis/personalization-options/deletepersonalizationoptionbyid.md): WARNING: Deleting a Personalization Option is permanent and cannot be undone. Using this endpoint is risky. ### List Personalization Options - [GET /personalization/property/option](https://developers.foleon.com/apis/personalization-options/listpersonalizationoptions.md): Query all Personalization Options available in your scope to return a list of Personalization Options. Use bracket notation in the parameters to filter and order the data. ### Create a Personalization Option - [POST /personalization/property/option](https://developers.foleon.com/apis/personalization-options/createpersonalizationoption.md): Create a new Personalization Option. ## Personalization Properties All endpoints related to Personalization Properties. ### Retrieve a Personalization Property - [GET /personalization/property/{property_id}](https://developers.foleon.com/apis/personalization-properties/getpersonalizationpropertybyid.md): Get a Personalization Property resource by it's ID. ### Update a Personalization Property - [PATCH /personalization/property/{property_id}](https://developers.foleon.com/apis/personalization-properties/patchpersonalizationpropertybyid.md): Update a Personalization Property's settings. ### Delete a Personalization Property - [DELETE /personalization/property/{property_id}](https://developers.foleon.com/apis/personalization-properties/deletepersonalizationpropertybyid.md): WARNING: Deleting a Personalization Property is permanent and cannot be undone. Using this endpoint is risky. ### List Personalization Properties - [GET /personalization/property](https://developers.foleon.com/apis/personalization-properties/listpersonalizationproperties.md): Query all Personalization Properties available in your scope to return a list of Personalization Properties. Use bracket notation in the parameters to filter and order the data. ### Create a Personalization Property - [POST /personalization/property](https://developers.foleon.com/apis/personalization-properties/createpersonalizationproperty.md): Create a new Personalization Property. ## Personalization Values All endpoints related to Personalization Values. ### Retrieve a Personalization Value - [GET /personalization/token/value/{value_id}](https://developers.foleon.com/apis/personalization-values/getpersonalizationvaluebyid.md): Get a Personalization Value resource by it's ID. ### Delete a Personalization Value - [DELETE /personalization/token/value/{value_id}](https://developers.foleon.com/apis/personalization-values/deletepersonalizationvaluebyid.md): WARNING: Deleting a Personalization Value is permanent and cannot be undone. Using this endpoint is risky. ### List Personalization Values - [GET /personalization/token/value](https://developers.foleon.com/apis/personalization-values/listpersonalizationvalues.md): Query all Personalization values available in your scope to return a list of Personalization Values. Use bracket notation in the parameters to filter and order the data. ### Create a Personalisation Value - [POST /personalization/token/value](https://developers.foleon.com/apis/personalization-values/createpersonalizationvalue.md): Create a new Personalization Value. ## Personalization Tokens All endpoints related to Personalization Tokens. ### Retrieve a Personalization Token - [GET /personalization/token/{token_id}](https://developers.foleon.com/apis/personalization-tokens/getpersonalizationtokenbyid.md): Get a Personalization Token resource by it's ID. ### Delete a Personalization Token - [DELETE /personalization/token/{token_id}](https://developers.foleon.com/apis/personalization-tokens/deletepersonalizationtokenbyid.md): WARNING: Deleting a Personalization Token is permanent and cannot be undone. Using this endpoint is risky. ### List Personalization Tokens - [GET /personalization/token](https://developers.foleon.com/apis/personalization-tokens/listpersonalizationtokens.md): Query all Personalization Tokens available in your scope to return a list of Personalization Tokens. Use bracket notation in the parameters to filter and order the data. ### Create a Personalization Token - [POST /personalization/token](https://developers.foleon.com/apis/personalization-tokens/createpersonalizationtoken.md): Create a new Personalization Token. ## Editing Content All endpoints related to editing the content of you Foleon Docs. ### Edit the content-tree of a Content Object - [POST /content/draft/{content_uuid}/mutation](https://developers.foleon.com/apis/editing-content/mutatecontent.md): Apply changes to the content using Immer-style patches, which represent updates based on immutable state mutation logic. These patches follow a format similar to JSON Patch but use array-based paths (e.g., ["table", 0, "row"]) instead of string pointers. ### Retrieve the mutation history of a content object. - [GET /content/draft/{content_uuid}/mutations](https://developers.foleon.com/apis/editing-content/getcontentmutations.md): Retrieve the history of Immer-style patches, that have been applied to the document. Up to 30 mutations are included in the response, along with inverse mutations to undo the mutation if needed. ### Get the content-tree of a Content Object - [GET /content/draft/type/{content_type}/reference/{resource_id}](https://developers.foleon.com/apis/editing-content/getcontent.md): Returns the content-tree of the object in json format. ## Foleon Analytics All endpoints related to Foleons native analytics. ### Get analytics data based on a query - [POST /analytics](https://developers.foleon.com/apis/foleon-analytics/getanalytics.md): Fetches detailed analytics data. The request body specifies the dimensions, measures, time dimensions, and filters for the query. Note: Always include pageviews.account_id in filters for better performance, as data is chunked on workspace/account_id. ## Media Library All endpoints related to managing media in Foleon's media library. ### List Documents - [GET /v2/document](https://developers.foleon.com/apis/media-library/listdocuments.md): Query all Documents available in your scope to return a list of Documents. Use bracket notation in the parameters to filter and order the data. Note that a 'Document' in this case, is a file stored in your Media Library, not to be confused with a Doc which is a Foleon Publication. ### Retrieve a Folder - [GET /topiary/{topiary_id}](https://developers.foleon.com/apis/media-library/gettopiaryebyid.md): Get a media library Folder by it's ID. ### Upload file(s) - [POST /file](https://developers.foleon.com/apis/media-library/uploadfile.md): Uploads files to a specified folder or account. ### Get an Image - [GET /image/{image_id}](https://developers.foleon.com/apis/media-library/getimagebyid.md): Get an Image from the Media Library by it's ID