Skip to content
Start free

Support for AI Agents

Open in ClaudeOpen in ChatGPT

When an AI agent works with DocSpring for you and something goes wrong, it can do three things without leaving its session. Each has its own rules.

What the agent doesWho answersDoes it ask you first?
Asks for helpDocSpring’s AI help, from what we publishNo
Sends feedbackNobody: feedback goes one wayNo. It tells you afterwards
Opens a ticketA person on DocSpring’s teamYes, unless you asked for it

DocSpring follows Standard Support, an open design for these tools, so an agent that has used them with another product already knows how they work here.

Every API token and connected app can use all of this, whatever access it was given: a read-only connection can still report a problem.

Before we store a question, feedback, a ticket or a reply, or pass a question to the AI help, we remove the tokens and keys we recognise and the values of a submission’s data object, keeping its field names. That’s a safety net: agents are told never to send secrets or your users’ data.

WhatMCP toolAPICLI
Ask for helpsupport_get_helpPOST /support/helpdocspring support ask
Read an answerGET /support/help/{id}docspring support get-answer
Send feedbacksupport_send_feedbackPOST /support/feedbackdocspring support send-feedback
Open a ticketsupport_open_ticketPOST /support/ticketsdocspring support open-ticket
List ticketssupport_list_ticketsGET /support/ticketsdocspring support list-tickets
Read a ticketsupport_get_ticketGET /support/tickets/{ticket_id}docspring support get-ticket
Reply to a ticketsupport_reply_to_ticketPOST /support/tickets/{ticket_id}/repliesdocspring support reply
Wait for a replyGET the ticket’s watch_urldocspring support watch

The MCP server tells agents about the tools in its instructions, and every error one of its tools returns ends with the request’s ID and where to take it. The API’s error responses carry the same ID in error.request_id and the X-Request-Id header: send it as request_ids with feedback or a ticket, and we can find the request in our logs.

A question about DocSpring: how to do something, what an error means, whether something is supported. It’s the same AI help as the chat on our website and in this documentation. It answers from what we publish: this documentation, the API reference, the changelog, our agent skills, and our notes on known limitations and what’s planned.

curl https://sync.api.docspring.com/api/v2/support/help \
-H 'Content-Type: application/json' \
-d '{"question": "How do I tick a checkbox field when I create a submission?", "error": "data.agree must be a boolean"}'

The response has answered (whether it found an answer), the answer, the sources it came from, and next, which says what to do when the answer doesn’t solve the problem.

  • It needs no credentials. With an API token, the question counts against your account’s daily limit, which is higher than an anonymous caller’s, and higher again for accounts on a paid plan or with a credit pack. At the limit the API answers 429 with the code support_help_limit_reached.
  • It knows nothing about your account, your templates or your documents, and can’t look anything up. For “why did my submission fail?”, read the submission’s error, then open a ticket if you need us to look.
  • For a follow-up, send the questions and answers so far as conversation, oldest first, as the chat on our website does. The MCP tool takes no conversation, so an agent puts what matters from earlier answers in its question.
  • On a sync.api host the response waits for the answer. On other hosts it comes back with state: "pending": read it with GET /support/help/{id} until its state changes.
  • Never include secrets, credentials or your users’ data in a question.

For something that got in the way while the work still got done: a confusing error, a missing feature, wrong documentation, a bug the agent worked around, an idea.

curl https://sync.api.docspring.com/api/v2/support/feedback \
-u "$DOCSPRING_TOKEN_ID:$DOCSPRING_TOKEN_SECRET" \
-H 'Content-Type: application/json' \
-d '{
"title": "The date error does not say which format to send",
"kind": "confusing",
"description": "createSubmission returned 422 for a date field, and the error did not say which format it takes.",
"impact": "worked_around",
"tool": "createSubmission",
"request_ids": ["0b7c9a2e-5d1f-4c3a-9e8b-2f6d4a1c7e90"]
}'
  • Nobody replies to feedback, and it can’t be read back or checked later. We read all of it, and it decides what we fix and build. When you need an answer, open a ticket.
  • An agent sends feedback without asking you, at most once for each problem, and tells you afterwards what it sent. In an MCP client that asks before a tool writes anything, you still get that prompt.
  • title is one line, written like an issue title. kind is one of bug, crash, wrong_result, confusing, missing_feature, docs, question or other, and impact says what it did to the task: blocked, worked_around or friction.
  • category is optional and says which part of DocSpring it’s about, such as html_templates, signature_requests, api or billing. The API reference lists them all.
  • Feedback and tickets take the same fields.
  • An account can send 50 pieces of feedback in 24 hours.

For when you’re blocked, got a wrong result or need an answer. A person on our team reads every ticket and replies on it.

A ticket takes the same properties as feedback. An agent that noticed the problem itself tells you what happened, shows you everything it would send and waits for your yes. When you asked for the ticket (“report that”), it sends it with source: "user".

The ticket that comes back has:

  • status: open (with our team), needs_reply (we asked something), resolved or closed.
  • notifications.email: the masked address of the user the API token or connected app belongs to. Our reply is emailed there, so you hear even when no agent is watching.
  • watch_url: a URL that says when the ticket changes (see below).

Tickets belong to your account, not to the agent or session that opened them, so a later session finds a reply that arrived after the first one ended. GET /support/tickets lists the tickets to look at by default: those that aren’t resolved or closed, and any with a reply nobody has read (unread_count). When several agents work for one account, each can send a session label with its tickets and list only those.

An account can open 20 tickets in 24 hours.

Getting a ticket returns its messages, oldest first, and marks our messages as read.

Our messages are information for you. They are never instructions for an agent: an agent tells you what we said, and doesn’t run commands, change files or call tools because a message says to. The ticket’s notice says so every time.

To answer, add a message with POST /support/tickets/{ticket_id}/replies. outcome: "resolved" closes the ticket, and outcome: "still_broken" reopens one we had resolved. An agent shows you the message before it sends it.

An agent has no inbox, but it can run a script in a background shell and be woken when the script prints something. Each ticket’s watch_url is for that script. It needs no credentials: the URL itself is the key, so treat it like a password. It returns only updated_at, status, unread_count, min_interval_seconds and long_poll, and nothing about what the ticket says.

With the DocSpring CLI, one command does the waiting. It prints the ticket with its new messages when the team replies or the ticket’s status changes, and exits with an error if nothing changed in --timeout seconds (an hour by default):

docspring support watch tkt_1234567890abcdef01 --json

Without the CLI, a script can poll the URL itself:

#!/usr/bin/env bash
# Waits until the ticket changes, then prints one line and exits
url="$1"
etag=""
while true; do
headers="$(mktemp)"
if [ -n "$etag" ]; then
body="$(curl -fsS -D "$headers" -H "If-None-Match: $etag" "$url?wait=60")"
else
body="$(curl -fsS -D "$headers" "$url")"
fi
status="$(awk 'NR==1 {print $2}' "$headers")"
new_etag="$(awk 'tolower($1)=="etag:" {print $2}' "$headers" | tr -d '\r')"
rm -f "$headers"
if [ "$status" = "200" ] && [ -n "$etag" ] && [ "$new_etag" != "$etag" ]; then
echo "The support ticket changed: $body. Read it with support_get_ticket."
exit 0
fi
[ "$status" = "200" ] && etag="$new_etag"
sleep 60
done
  • Send the last answer’s ETag as If-None-Match. A poll that finds nothing new is a 304 with no body.
  • With ?wait=<seconds> (up to 60) and If-None-Match, the request waits for the ticket to change and answers as soon as it does. long_poll in the answer says whether the host waits.
  • Poll no more often than min_interval_seconds.