Open311 API documentation
Read and submit City of Smithville 311 service requests from your own app. The API follows Open311 GeoReport v2, so tools built for other cities work here too.
Getting started
Every endpoint lives under https://clear311.cloud.sweent.net/api/v2. Reading is open to everyone; submitting requests needs an API key. Try it from a terminal:
curl "https://clear311.cloud.sweent.net/api/v2/services.json"
- List services to get the
service_codefor each kind of problem. - Read a service definition for the questions that service asks.
- Submit a request with your key, then follow it with Get one request or Status updates.
The full standard is on the Open311 wiki. Requests from the API land in the same queue as the website’s, and residents’ names and contact details are never returned.
Authentication and API keys
Send your key in the X-API-Key header (best), or as api_key in the query string or the body. Each key only reaches the endpoints the City allowed for it; other endpoints answer 403.
- Reading services, requests and updates works without a key, at a lower rate limit.
- Submitting a request needs a key.
- Posting a status update always needs a key.
- When the City issues a new key for your app, the old one stops working at once. Update your app as soon as you get it.
To request an API key, contact the City of Smithville 311 team with your app’s name, what it does and a contact address.
Formats (JSON and XML)
End any path with .json or .xml to choose the format, or add ?format=xml. Without either you get JSON. POST bodies can be a form (application/x-www-form-urlencoded) or JSON, up to 100 KB.
curl "https://clear311.cloud.sweent.net/api/v2/services.xml" <?xml version="1.0" encoding="utf-8"?><services><service><service_code>POTHOLE</service_code>…</service></services>
Rate limits
- Without a key: 10 calls a minute per IP address.
- With a key: 60 calls a minute per key by default. The City can set a different limit for each key.
- Discovery is not limited.
Every limited response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time when the minute ends). Over the limit you get 429 with a Retry-After header in seconds.
Errors
Errors use the Open311 form: a list with one entry per problem.
[
{
"code": "400",
"description": "service_code: Choose what the problem is"
}
]| Status | Meaning |
|---|---|
| 400 | A parameter is missing or not valid (one entry per field), or an unknown jurisdiction_id. |
| 401 | The key is missing, wrong, revoked or expired. |
| 403 | The key is not allowed to call this endpoint. |
| 404 | Unknown endpoint, service or request, or the City has turned the API off. |
| 413 | The body is larger than 100 KB. |
| 429 | Too many calls this minute. Wait for Retry-After. |
| 500 | Something went wrong on our side. Try again. |
/api/v2/discovery.jsonDiscovery
Where the API lives, which formats it speaks and where to ask for a key. Start here if your app works with many cities.
Access: Open to everyone, no key and no rate limit.
| Parameter | Required | Description |
|---|---|---|
jurisdiction_id | No | This city’s ID (see discovery). Any other value is rejected with 400. |
curl "https://clear311.cloud.sweent.net/api/v2/discovery.json"Example response · 200 OK
{
"changeset": "2026-09-01T00:00:00Z",
"contact": "City of Smithville 311",
"key_service": "https://clear311.cloud.sweent.net/developers",
"endpoints": [
{
"specification": "http://wiki.open311.org/GeoReport_v2",
"url": "https://clear311.cloud.sweent.net/api/v2",
"changeset": "2026-09-01T00:00:00Z",
"type": "production",
"formats": [
"application/json",
"text/xml"
]
}
]
}/api/v2/services.jsonList services
Every kind of problem residents can report, with its service_code. metadata is true when the service asks extra questions (see the service definition).
Access: Open to everyone. With a key, 60 calls a minute unless the City set another limit for it; without one, 10 a minute per IP address.
| Parameter | Required | Description |
|---|---|---|
jurisdiction_id | No | This city’s ID (see discovery). Any other value is rejected with 400. |
api_key | No | Your key, if you have one: calls count against its limit instead of the anonymous one. Or send it as an X-API-Key header. |
curl "https://clear311.cloud.sweent.net/api/v2/services.json"Example response · 200 OK
[
{
"service_code": "POTHOLE",
"service_name": "Pothole",
"description": "A hole or broken pavement in a street",
"metadata": true,
"type": "realtime",
"keywords": "road,street,asphalt,hole",
"group": "Streets & Roads"
},
{
"service_code": "SIDEWALK",
"service_name": "Sidewalk damage",
"description": "Cracked, raised or missing sidewalk and curb ramps",
"metadata": false,
"type": "realtime",
"keywords": "sidewalk,trip,curb,ramp",
"group": "Streets & Roads"
}
]/api/v2/services/{service_code}.jsonService definition
The extra questions one service asks, in order. Send the answers as attribute[code] when you submit a request.
Access: Open to everyone. With a key, 60 calls a minute unless the City set another limit for it; without one, 10 a minute per IP address.
| Parameter | Required | Description |
|---|---|---|
service_codein the path | Yes | From List services, e.g. POTHOLE. Unknown or retired codes return 404. |
jurisdiction_id | No | This city’s ID (see discovery). Any other value is rejected with 400. |
api_key | No | Your key, if you have one: calls count against its limit instead of the anonymous one. Or send it as an X-API-Key header. |
curl "https://clear311.cloud.sweent.net/api/v2/services/POTHOLE.json"Example response · 200 OK
{
"service_code": "POTHOLE",
"attributes": [
{
"variable": true,
"code": "size",
"datatype": "singlevaluelist",
"required": true,
"datatype_description": null,
"order": 1,
"description": "Approximate size",
"values": [
{
"key": "small",
"name": "Smaller than a dinner plate"
},
{
"key": "medium",
"name": "Up to a car tire"
},
{
"key": "large",
"name": "Larger than a car tire"
}
]
}
]
}/api/v2/requests.jsonSearch requests
Public requests, newest first. Residents’ names and contact details are never included, and requests held for review are left out.
Access: Open to everyone. With a key, 60 calls a minute unless the City set another limit for it; without one, 10 a minute per IP address.
| Parameter | Required | Description |
|---|---|---|
service_request_id | No | One or more request IDs or tracking numbers, comma-separated. |
service_code | No | One or more service codes, comma-separated. |
status | No | open or closed. |
start_date | No | Reported on or after this ISO 8601 date and time. |
end_date | No | Reported on or before this ISO 8601 date and time. |
agency_responsible | No | Department ID or name, e.g. Department of Public Works. |
lat, long | No | Search around a point (WGS84). Send both or neither. |
radius | No | Meters around lat, long (default 1000). |
page | No | Page number, from 1 (default 1). |
page_size | No | Results per page, 1 to 100 (default 50). The X-Total-Count header has the total. |
jurisdiction_id | No | This city’s ID (see discovery). Any other value is rejected with 400. |
api_key | No | Your key, if you have one: calls count against its limit instead of the anonymous one. Or send it as an X-API-Key header. |
curl "https://clear311.cloud.sweent.net/api/v2/requests.json?service_code=POTHOLE&status=open"Example response · 200 OK
[
{
"service_request_id": "service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556",
"token": "L2RLZN7X",
"status": "open",
"status_detail": "new",
"service_name": "Pothole",
"service_code": "POTHOLE",
"description": "Pothole next to the crosswalk, bikes are hitting it",
"agency_responsible": "Department of Public Works",
"service_notice": "Sent to the Department of Public Works.",
"requested_datetime": "2026-09-26T16:17:03.566Z",
"updated_datetime": "2026-09-26T16:17:03.566Z",
"expected_datetime": null,
"closed_datetime": null,
"address": "5th Ave & Main St",
"address_id": null,
"zipcode": null,
"lat": 40.716248,
"long": -73.99973,
"media_url": null,
"merged_into": null
}
]/api/v2/requests/{id}.jsonGet one request
One public request, by its ID or its 8-character tracking number.
Access: Open to everyone. With a key, 60 calls a minute unless the City set another limit for it; without one, 10 a minute per IP address.
| Parameter | Required | Description |
|---|---|---|
idin the path | Yes | The service_request_id or the tracking number (token). |
jurisdiction_id | No | This city’s ID (see discovery). Any other value is rejected with 400. |
api_key | No | Your key, if you have one: calls count against its limit instead of the anonymous one. Or send it as an X-API-Key header. |
curl "https://clear311.cloud.sweent.net/api/v2/requests/L2RLZN7X.json"Example response · 200 OK
{
"service_request_id": "service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556",
"token": "L2RLZN7X",
"status": "open",
"status_detail": "new",
"service_name": "Pothole",
"service_code": "POTHOLE",
"description": "Pothole next to the crosswalk, bikes are hitting it",
"agency_responsible": "Department of Public Works",
"service_notice": "Sent to the Department of Public Works.",
"requested_datetime": "2026-09-26T16:17:03.566Z",
"updated_datetime": "2026-09-26T16:17:03.566Z",
"expected_datetime": null,
"closed_datetime": null,
"address": "5th Ave & Main St",
"address_id": null,
"zipcode": null,
"lat": 40.716248,
"long": -73.99973,
"media_url": null,
"merged_into": null
}/api/v2/requests.jsonCreate a service request
Submits a new request into the same queue as the website. Send the fields as a form (application/x-www-form-urlencoded) or as JSON. Give a location as lat + long, or as address_string.
Access: Needs an API key allowed to submit. 60 calls a minute per key by default.
| Parameter | Required | Description |
|---|---|---|
api_key | Yes | Your key, or send it as an X-API-Key header. |
service_code | Yes | From List services, e.g. POTHOLE. |
description | Yes | What’s wrong, 10 to 4,000 characters. |
lat, long | One of | WGS84 coordinates inside city limits. |
address_string | One of | Street address. |
address_id | No | Your own ID for the address. |
zipcode | No | Postal code. |
attribute[code] | Varies | Answers to the service’s questions (Service definition). Required questions must be answered. |
email | No | The resident’s email, for updates. Never shown publicly. |
phone | No | The resident’s phone, with area code. Never shown publicly. |
first_name, last_name | No | The resident’s name. Never shown publicly. |
device_id | No | Your app’s ID for the device, used to spot repeated reports. |
media_url | No | Link to one photo. |
jurisdiction_id | No | This city’s ID (see discovery). Any other value is rejected with 400. |
curl -X POST "https://clear311.cloud.sweent.net/api/v2/requests.json" \ -H "X-API-Key: YOUR_KEY" \ --data-urlencode "service_code=POTHOLE" \ --data-urlencode "lat=40.7162" \ --data-urlencode "long=-73.9997" \ --data-urlencode "description=Deep pothole in the right lane" \ --data-urlencode "attribute[size]=large"Example response · 200 OK
[
{
"service_request_id": "service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556",
"token": "L2RLZN7X",
"service_notice": "Sent to the Department of Public Works.",
"account_id": null
}
]/api/v2/servicerequestupdates.jsonStatus updates
Public updates on requests, newest first: status changes and notes from the City. Poll this to keep your copy of requests current.
Access: Open to everyone. With a key, 60 calls a minute unless the City set another limit for it; without one, 10 a minute per IP address.
| Parameter | Required | Description |
|---|---|---|
service_request_id | No | One or more request IDs or tracking numbers, comma-separated. |
start_date | No | Updated on or after this ISO 8601 date and time. |
end_date | No | Updated on or before this ISO 8601 date and time. |
page | No | Page number, from 1 (default 1). |
page_size | No | Results per page, 1 to 100 (default 50). The X-Total-Count header has the total. |
jurisdiction_id | No | This city’s ID (see discovery). Any other value is rejected with 400. |
api_key | No | Your key, if you have one: calls count against its limit instead of the anonymous one. Or send it as an X-API-Key header. |
curl "https://clear311.cloud.sweent.net/api/v2/servicerequestupdates.json?page_size=10"Example response · 200 OK
[
{
"update_id": "service_request_update:service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556:2026-09-27T09-16-03-566Z:1feb33e3",
"service_request_id": "service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556",
"token": "L2RLZN7X",
"status": "in_progress",
"description": "A crew is scheduled for Thursday.",
"updated_datetime": "2026-09-27T09:16:03.566Z",
"updated_by": null,
"media_url": null
}
]/api/v2/servicerequestupdates.jsonPost a status update
For partner systems that do the work (a contractor’s work-order system, say): moves a request to a new status with a public note, as long as the move is allowed from its current status.
Access: Always needs an API key allowed to post updates. 60 calls a minute per key by default.
| Parameter | Required | Description |
|---|---|---|
api_key | Yes | Your key, or send it as an X-API-Key header. |
service_request_id | Yes | The request ID or tracking number. |
status | Yes | The new status, e.g. in_progress or fixed. |
description | Yes | The public note residents will see. |
update_id | No | Your own ID for this update. |
media_url | No | Link to one photo. |
jurisdiction_id | No | This city’s ID (see discovery). Any other value is rejected with 400. |
curl -X POST "https://clear311.cloud.sweent.net/api/v2/servicerequestupdates.json" \ -H "X-API-Key: YOUR_KEY" \ --data-urlencode "service_request_id=L2RLZN7X" \ --data-urlencode "status=fixed" \ --data-urlencode "description=Patched the pothole."Example response · 200 OK
{
"update_id": "service_request_update:service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556:2026-09-28T14-02-11-020Z:0a1b2c3d",
"service_request_id": "service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556",
"status": "success"
}Questions about the API? Contact the City of Smithville 311 team, or read about City of Smithville 311.