API User Documentation Overview – OpenCities

These user guides are for users with experience working with API keys to send and receive data between applications. You must also have the OC Developer role to access API Management.

Overview

The OpenCities API provides methods to help build more powerful integrations with OpenCities. You can create and manage multiple API keys for your website and use them to manage:

Forms
Form responses
Content pages
Files
Folders
Addresses and waste management
Embeds

Please note the following:

Base URL: /api/v1
Supported formats: JSON, XML
Authentication: Basic Authentication

Authentication

All API endpoints (except those marked as "No authentication required") require Basic Authentication using API credentials.

curl -u "your_app_id:your_api_key" \
  -H "Content-Type: application/json" \
  "https://your-domain.com/api/v1/endpoint"

Error Handling

Common Response Codes

200: Success
400: Invalid Input - The request parameters are invalid
401: Access Denied - Authentication failed or API token is invalid
404: Not Found - The requested resource does not exist
409: Conflict - Resource conflict (e.g., file has links and cannot be deleted)
500: Internal Server Error

Sample Error Response

{
  "code": 400,
  "message": "Required parameter missing error",
  "fields": "fieldName"
}

Additional Notes

Date Formats: All dates should be in ISO 8601 format (e.g., 2023-10-15T14:30:00Z)
UUIDs: All ID fields expect UUID format (e.g., 123e4567-e89b-12d3-a456-426614174000)
File Uploads: Use multipart/form-data for file upload endpoints
Language Codes: Use standard language codes (e.g., en-AU, en-US)
Pagination: Most list endpoints support offset and limit parameters for pagination

For additional support or questions about specific endpoints, please refer to the API user guides or contact support.