Working with the Civio Engage API | Civio Engage Knowledge Base [Skip to content](#main) [ ![Civio Engage Knowledge Base](/civio-light.svg) ](https://engage.knowledge.civ.io) [Product documentation](/articles) [Release notes](/releases) [Roadmap](/roadmap) [ Support portal ](https://engage.knowledge.civ.io/portal/login) Toggle navigation [Product documentation](/articles) [Release notes](/releases) [Roadmap](/roadmap) [Support portal](https://engage.knowledge.civ.io/portal/login) 1. [Home](/) › 2. [Product documentation](/articles) › 3. [Setting up Civio Engage ](/articles?category=2) › 4. Working with the Civio Engage API Working with the Civio Engage API ================================= Updated 2 weeks ago · 7 min read Search Search The Civio Engage API lets you connect your site to other systems and manage its content programmatically. This article is written for technical staff and integration partners building connections to your site. What you can do with the API ---------------------------- The API lets an authorised integration work with your site's main content areas: - Create, update and delete projects; control whether they're published - Build and edit surveys; read their structure; create, read, moderate and remove survey responses - Manage content pages, project updates (news posts) and timeline stages - Manage events, maps and their hotspots, and documents - Manage your classification tags and regions Changes made through the API follow the same rules, permissions and publishing workflow as changes made in the dashboard. An API update behaves exactly as if you'd made that change on screen. Getting access -------------- Every API request needs a personal access token for authentication. You need an administrator account to create tokens; you generate and manage them in your dashboard account settings. The full setup steps are in [Creating an API Key](/articles/13526958469263-Creating-an-API-Key). ![Creating a personal access token in Civio Engage](/storage/14AXh7oyBKNCLNy0cdfAGFFVVVGWSdlhkNMVCdh2.gif) A token inherits all permissions from the account that created it. A request can only access projects, teams and content that account is allowed to see; content moderation rules still apply. If you need to limit an integration to certain projects, create its token from an account that only has access to those projects. #### Keep tokens safe Treat a token like a password. Store it securely; never put it in public code or browser scripts. Give each integration its own named token so you can track and revoke them individually. If a token is exposed or an integration is retired, revoke it immediately from your account. If a token stops working, create a new one and update the integration. The interactive API documentation --------------------------------- The definitive reference for your site lives at **/docs/api** on your domain (for example `https://yourdomain.com/docs/api`). You need to be signed in as an administrator to view it. It's generated directly from your live site's code, so it always shows the endpoints and features you actually have. Use it to: - Browse every available endpoint grouped by content type - See the exact format of requests and responses - Test calls directly in the browser - Confirm the current path and parameters for your setup ![](https://engage.knowledge.civ.io/storage/9RFC9ne1vzsOOvZ0D7cenEE7qph0vttgxdM1S3wA.png) Because **/docs/api** is generated from your live site, it shows exactly which endpoints and features are active on your installation. Treat it as the definitive reference; it always reflects your actual setup. How requests and responses work ------------------------------- The API follows consistent patterns across every resource, so once you understand one area, the rest work the same way. - All endpoints sit under `/api/v1` - Use **GET** to read, **POST** to create, **PATCH** to update, **DELETE** to remove - Create operations return `HTTP 201`; updates return `200` with the updated record; deletions return `204` with no body - If validation fails, you get `HTTP 422` with a JSON body explaining which fields need attention - Content within a project can usually be reached two ways: globally (all content across the site) or scoped to one project (that project's content only) ### Versioning The API version sits in the address. Everything today is under `/api/v1`. If a future release needs backwards-incompatible changes, it will be introduced under a new version prefix (like `/api/v2`), so integrations built against `v1` keep working. ### Rate limits Requests are rate-limited per authenticated user (or by client IP for unauthenticated requests) to prevent any single integration from overloading your site. The default limit is 60 requests per minute. If you exceed it, further requests return `HTTP 429` until the window resets. Space your requests out. If a genuine integration needs a higher limit, contact the Civio Engage team; the limit is configurable per site. ### Controlling list responses List endpoints share a common set of controls so you can fetch exactly what you need: - **Filtering** - narrow a list with `filter[...]` parameters (see the projects example below) - **Sorting** - order results with `sort`; prefix a field with `-` for descending order - **Pagination** - results are paged; step through them with the `page` parameter What each area lets you do -------------------------- The table below summarises the main content areas and available operations. For exact paths, parameters and field lists for your site, use **/docs/api**. AreaWhat you can manageReadCreateUpdateDelete**Projects**Consultation/engagement projects and their published stateYesYesYesYes**Surveys**Survey definitions, including their field structureYesYesYesYes**Survey submissions**Responses to a survey, including moderation statusYesYesYesYes**Pages**Content pages (global or within a project)YesYesYesYes**Updates**Project updates / news postsYesYesYesYes**Stages**Timeline stages on a projectYesYesYesYes**Events**Events (global or within a project)YesYesYesYes**Maps & hotspots**Interactive maps and the hotspots placed on themYesYesYesYes**Documents**Files in the document libraryYesYesYesYes**Tags & regions**Classification tags and regions used to categorise contentYesYesYesYesSome areas are only available if that feature is enabled on your site. Your **/docs/api** page shows exactly which endpoints and features are available on your installation. ### xample: listing your open projects You can filter the projects list by consultation status using the status name. This makes it straightforward to embed a live listing of open projects on an external website. Supported status values: - `open` - `in_progress` - `reviewing` - `reporting_back` - `closed` For example, requesting `/api/v1/projects?filter[consultation_status]=open` returns only your open projects. (The filter also accepts the numeric status ID if you prefer.) Reading a survey's structure ---------------------------- When you pull survey data through the API, the survey record includes a `form_fields` list that describes the questionnaire. Each field gives you: - `name` - the key used for that field in response data - `label` - the question text as respondents see it - `type` - the field type (for example, text, choice, or date) This lets an integration rebuild the full questionnaire, line each answer up against its question, and keep everything in the right order. It works for every survey type, including group surveys. Example survey response: ``` { "id": 17, "title": "Community Feedback Survey", "form_fields": [ { "name": "full_name", "label": "Your name", "type": "Text" }, { "name": "priorities", "label": "Your top priorities", "type": "Checkbox" }, { "name": "comments", "label": "Any other comments", "type": "Text area" } ] } ``` Recommended flow: fetch the survey first (to get `form_fields`), then read the responses and use each field's `name` to match an answer to its question, using `label` and `type` for display and ordering. The survey definition is served from `/api/v1/surveys/`; check **/docs/api** for the exact path for each survey type. The survey's full HTML body is returned only when you request a single survey, not in list responses. Common uses ----------- A few patterns councils and their partners use most often: **Show your open consultations on your main website.** Call the projects endpoint filtered to open projects from your corporate site or intranet, and render a live, always-current list that links back to each project. **Pull responses into your reporting or data tools.** Fetch a survey to get its `form_fields`, then read its responses and line each answer up against its question; ready to load into a data warehouse, BI dashboard or spreadsheet on a schedule. **Create or update content from another system.** Have an internal system draft a project, publish a news update, add a timeline stage, or lodge a survey response through the API, so your team maintains content where they already work instead of re-keying it in the dashboard. **Keep events in sync.** Read events for a project or across the whole site to feed a corporate calendar, or push events in from another system so they appear on your engagement site automatically. Connecting from another website ------------------------------- API responses carry a strict security policy. By default, the API doesn't accept cross-origin browser requests from other domains. If you want a browser-based integration on your own website (for example, a script on your main council site) to call the API directly, your IT team or integration partner can request those domains be added to an allow-list for your site. Server-to-server integrations aren't affected and work without allow-listing. Allow-listing is configured per site. Let the Civio Engage team know the exact domains your integration will call from, and they'll set it up for you. Need help? ---------- For endpoint reference for your site, always check **/docs/api** first. For anything else, including setting up cross-origin access or planning an integration, contact the [Civio Engage Support Team](mailto:support@civ.io). Was this article helpful? ------------------------- Your feedback helps us prioritise what to rewrite. Yes No [ Back to Setting up Civio Engage ](/articles?category=2) On this page ### Still need help? Raise a request in the support portal and track it to resolution. [ Submit a support request ](https://engage.knowledge.civ.io/portal/login) Submit a support request through the [support portal](/portal) or email . © 2026 [Civio](https://civ.io) [Privacy Policy](/articles/privacy-policy) [Terms of Use](/articles/terms-of-use)