Deutsche Version

Back to overview

API Endpoints: Troubleshooting

This documentation always describes the latest published version.

Troubleshooting

Symptom: 404 Not Found for endpoints with a path parameter, for example /api/tickets-get.php/123456.json.

Check: Does /api/.htaccess contain the block that starts with API Endpoints Plugin - Apache Rewrite Rules? Are the endpoint files tickets-*.php present in /api/? On NGINX: is there a location block with PATH_INFO for the endpoint?

Solution: On Apache, disable and re-enable the plugin, which deploys files and rules again. If /api/.htaccess is missing, add the rules from htaccess.template yourself and make sure .htaccess overrides are allowed. On NGINX, use the configuration from Installation. Note that all four subticket endpoints need PATH_INFO as well.

Symptom: 500 with the message API Endpoints Plugin not properly installed.

Check: Is the plugin folder named exactly api-endpoints and located in /include/plugins/?

Solution: Rename the folder. A clone of the repository is named osticket-api-endpoints by default, which is wrong.

Symptom: 401 with API key not authorized to read tickets or a similar message.

Check: The message names the missing permission. Is the permission enabled for exactly this API key under Manage → Plugins → API Endpoints → Configure → API Key Permissions?

Solution: Enable the permission, see Configuration. If the permission checkboxes do not show up, disable and re-enable the plugin once, which creates the missing columns.

Symptom: 403 with API key not authorized for subticket operations.

Check: Is can_manage_subtickets enabled for this API key? The message Access denied to ... department only occurs when the API key object provides department restrictions. Standard osTicket API keys have none.

Solution: Enable can_manage_subtickets for the key.

Symptom: 501 with Subticket plugin not available.

Check: Is the Subticket Manager plugin installed and enabled?

Solution: Install and enable it. The creation and update endpoints with parentTicketNumber work without it, only the four subticket endpoints need it.

Symptom: 403 with Attachment not accessible.

Check: Does the file_id come from the attachment metadata of a thread entry, see GET Retrieve Ticket?

Solution: Use a file_id from a ticket thread. The endpoint answers 403 when no row with this file_id exists in the attachment table.

Symptom: 400 with Markdown Support plugin is required but not active on ticket creation.

Check: Is Require Markdown Plugin enabled in the plugin settings and the Markdown Support plugin not active?

Solution: Enable the Markdown Support plugin, or switch off Require Markdown Plugin.

Symptom: 405 with Method Not Allowed. Use GET.

Check: Does the HTTP method match the endpoint? Search, get, statistics, statuses, parent, list and attachment download take GET, delete and unlink take DELETE, update takes PATCH or PUT, subticket create takes POST.

Symptom: 400 with Invalid URL format. Expected: ....

Check: The path must end in .json or .xml and carry the number, for example /api/tickets-get.php/781258.json. Ticket numbers must not contain a dot.

Symptom: A ticket update changed only part of the fields.

Check: The fields are applied one after another and not as a transaction. The response names the first failing value, the fields before it were already saved. The field priority is not supported by the update.

Known Limitations

• Search, statistics and the status list take no path parameter. Their path info after the script name is optional and may be .json or .xml, without it the response is JSON.
• The statistics endpoint iterates over all tickets on every call and is slow on large installations.
• Attachments of an update are only stored together with a note, otherwise they are ignored without an error.
• The plugin implements no rate limiting.
• Saving the permissions on the plugin page applies the checkboxes of all keys. If no permission checkbox of any key is ticked (the Read Stats checkbox alone does not count), the form is not processed, so permissions cannot be taken away from every key in one save.

FAQ

Which formats do the endpoints return? Endpoints with {number}.{format} return JSON or XML depending on the extension, create, update and delete return the ticket number as plain text.

Can I use names instead of IDs? Yes, for department, status, help topic and SLA by name. Staff members are found by ID, username or email address. See API Documentation.

Do I need the Subticket Manager plugin? Only for the four subticket endpoints.

Does the plugin work together with API Key Wildcard? Yes. If that plugin is installed, the standalone endpoints and the update route use its key validation. The create route POST /api/tickets.json does not call it.