Send findings and questions
Your account has a channel to the vrtmv engineers. Through it you can report what vrtmv got wrong, ask a question, and hold a conversation until it is settled. It is part of the Vrtmv API, and it is not billable: nothing you send through it uses a license or counts toward usage.
You can use it in three ways:
- Threads are conversations. You open one with a subject and a first message, the engineers reply in it, and either side can reply again. Use a thread when you expect a back-and-forth.
- Findings are one-way reports with a category. Use one when you want a record of a defect or a gap.
- Questions are one-way questions. The answer comes back on the question.
From an AI assistant, the vrtmv mcp server does the same through vrtmv_send, vrtmv_inbox, vrtmv_thread, vrtmv_mark_read and vrtmv_subscribe. See mcp and Use vrtmv with AI.
What to send, and when
Send a finding or open a thread when:
- vrtmv did something wrong on a host: a step failed, a result is wrong, or a report does not match the host;
- vrtmv does not cover something you need: a package, a configuration file, a service;
- you have a result or a reading you want on record with us.
Ask a question when you need an answer from an engineer, such as how a command behaves or what a report line means.
Describe what vrtmv did, what you expected, and the command you ran. Name packages, versions and error messages: they are what an engineer needs. Most are stored as you write them; the exceptions are under What is stripped before storage. Do not send credentials, configuration file contents or customer data. The stripping described below is a second line of defence, not a reason to paste them in.
The three finding categories
A finding is filed with exactly one category:
| Category | Use it for |
|---|---|
bug | vrtmv did something wrong. |
coverage | vrtmv does not cover something: a package, a configuration file, a service. |
measurement | A result or reading you want on record. |
Any other value is refused with 400 and the message category must be one of: bug, coverage, measurement. Threads have no category. A thread's kind is finding or question.
What is stripped before storage
Before a finding, a question, a thread subject or a message is stored, the API replaces the parts of the text that identify your hosts. This happens on the server, before the text is written, so the original text is never stored.
| In your text | Stored as |
|---|---|
A host or domain name, such as web01.corp.example.com or db.internal | <host> |
| A URL | <host> |
An absolute, home-relative or Windows path, such as /etc/httpd/conf.d/ssl.conf | <path> |
An IPv4 address, with or without a port, or an IPv6 address without a port, such as fe80::1 | <addr> |
| An email address | <email> |
| A long token: a vrtmv API token, a UUID, a hex digest, a base64 string | <id> |
| A JSON Web Token | <jwt> |
For example, this message:
httpd fails to start on web01.corp.example.com after the move: AH00526 in /etc/httpd/conf.d/ssl.conf line 12, upstream 10.20.0.15:8443 unreachable
is stored as:
httpd fails to start on <host> after the move: AH00526 in <path> line 12, upstream <addr> unreachable
Error codes such as AH00526, and names without a dot such as httpd or perl-Net-SSLeay, stay as they are. So does a dotted name whose last part holds a digit or an underscore, such as openssl-3.0.7-24.el9 or bash-5.1.8-6.el9.x86_64.
A dotted name whose last part is two or more letters has the shape of a host name, and is stored as <host>. That takes in a unit name such as httpd.service, a file name such as ssl.conf, a package such as perl-Net-SSLeay.noarch, and a version that ends in letters such as nginx-1.20.1-1.el7.ngx. To keep such a name, write it without that last part: the httpd service, the perl-Net-SSLeay package.
Line breaks and repeated spaces are stored as single spaces.
The stripping works on the shape of each word. A bare host name with no dots, such as dbprod01, or a customer name in a sentence, looks like any other word and is stored as it is. An IPv6 address in brackets with a port, such as [fe80::1]:22, is also stored as it is. Leave such names and addresses out of what you send.
Limits
Each field has a length limit. Text that is too long is refused with 400; it is not cut short. An empty field is also refused with 400.
| Field | Longest |
|---|---|
Finding title, thread subject | 200 bytes |
Finding evidence, thread message | 2048 bytes |
question | 2000 bytes |
The number of writes is capped per account. A write over a cap is refused with 429, and the message names the cap, such as collaboration write limit exceeded (50/day).
| What | Per minute | Per day |
|---|---|---|
| New findings, new questions, new threads and replies, together | 10 | |
| New findings and new questions, together | 50 in any 24 hours | |
| Messages you write on threads: replies, the first message of each thread you open, and the first message of the thread each finding or question opens | 50 in any 24 hours | |
| Thread status changes | 10 | 100 per UTC day |
| Marking a thread read | 60 | 1000 per UTC day |
Each finding and each question opens a thread with your text as its first message, so it also counts toward the 50 messages on threads. Fifty findings and questions in a day leave no room for replies or new threads until the oldest of them is more than 24 hours old.
Your plan's API rate limit applies as well.
Everything on this channel belongs to your account. A finding, question or thread id from another account answers 404, the same as an id that does not exist.
Send with curl
Every request carries your API token as Authorization: Bearer <token>. See Authentication. The examples read it from VRTMV_API_KEY.
Open a thread:
curl -sS https://api.vrtmv.com/v1/threads \
-H "Authorization: Bearer $VRTMV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"subject": "httpd does not start after the move",
"kind": "finding",
"message": "AH00526 in the ssl.conf vrtmv wrote, line 12. Command: vrtmv migrate ..."}'
kind is finding or question. The answer is the thread, with its id in id and its status (open). A thread in an answer, a list or an event names its kind as origin_kind; the request may send either name.
Reply on a thread:
curl -sS https://api.vrtmv.com/v1/threads/<thread-id>/messages \
-H "Authorization: Bearer $VRTMV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "Same result with the latest release."}'
File a finding:
curl -sS https://api.vrtmv.com/v1/findings \
-H "Authorization: Bearer $VRTMV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"category": "coverage",
"title": "No translation for a package we install",
"evidence": "vrtmv resolve reports no candidate for this package on the target release."}'
The answer is the finding, with its id and status (received).
Ask a question:
curl -sS https://api.vrtmv.com/v1/questions \
-H "Authorization: Bearer $VRTMV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "Does vrtmv verify compare service state as well as packages?"}'
The answer is the question, with its id and status (received).
The answer to each of these shows the text as it was stored, so you can see what was stripped.
How replies reach you
Your inbox
GET /v1/threads lists your account's threads, newest activity first. Each thread has status, message_count and unread, the number of messages you have not read yet. Filter with ?status=, ?kind= (finding, question or announcement) and ?unread=true; ?limit= takes 1 to 100 (default 50).
curl -sS "https://api.vrtmv.com/v1/threads?unread=true" \
-H "Authorization: Bearer $VRTMV_API_KEY"
GET /v1/threads/<thread-id> returns the thread and its messages. Each message has an author, customer or operator; operator is a vrtmv engineer. POST /v1/threads/<thread-id>/read marks the thread read up to its newest message.
A thread's status is open, triaged, in_progress or resolved. The engineers move it through those. You can set resolved to accept a resolution, or open to reopen it:
curl -sS -X PATCH https://api.vrtmv.com/v1/threads/<thread-id> \
-H "Authorization: Bearer $VRTMV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "resolved"}'
Setting triaged or in_progress yourself is refused with 403. A status other than these four is refused with 400.
When the engineers post an update for your account, it arrives as a thread of kind announcement. You can reply on it like any other thread.
Findings and questions are read back the same way:
GET /v1/findingsandGET /v1/findings/<id>. A finding'sstatusisreceived,triaged,in_progress,fixedorshipped. A fixed finding names the release with the fix infixed_in_release.GET /v1/questionsandGET /v1/questions/<id>. An answered question hasstatusanswered, with the reply inanswerand the time inanswered_at.
Wait for the next event
GET /v1/collab/subscribe holds the request open until something happens on your account's threads, then answers at once. Pass the cursor from each answer as since in the next request:
curl -sS "https://api.vrtmv.com/v1/collab/subscribe?since=0&wait=25" \
-H "Authorization: Bearer $VRTMV_API_KEY"
{
"cursor": 42,
"events": [
{
"seq": 42,
"op": "message_posted",
"thread": "thr_…",
"subject": "httpd does not start after the move",
"status": "triaged",
"origin_kind": "finding",
"message": "msg_…",
"author": "operator",
"body": "…",
"at": "…"
}
]
}
op is thread_created, message_posted or status_changed. message, author and body are present only on message_posted. since=0 starts at the beginning of your account's feed. wait is in seconds, at most 25 (the default), and 0 returns at once. When nothing happens within wait, the answer has no events and the same cursor. limit takes 1 to 100 events (default 100). Marking a thread read is not an event. An event's status is the thread's status when you read the feed, not when the event happened.
Webhook
The API can post the same events to a URL of yours. One URL per account:
curl -sS https://api.vrtmv.com/v1/webhooks \
-H "Authorization: Bearer $VRTMV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/vrtmv", "confirm": true}'
The answer holds the signing secret, which starts whsec_. It is returned only once, so store it then. Every POST needs "confirm": true, the first included, because a POST replaces any URL already set and issues a new secret; without it the answer is 400. GET /v1/webhooks shows the URL without the secret, and DELETE /v1/webhooks removes it.
Each delivery is a POST of JSON in the same shape as a subscribe answer: cursor and events. Its headers:
X-Vrtmv-Signature: sha256=<hex>, the HMAC-SHA256 of the raw request body, keyed with the whole secret,whsec_included;X-Vrtmv-Event: collab;X-Vrtmv-Delivery, an id for the delivery.
To check a delivery, compute the HMAC over the body bytes exactly as they arrived and compare it with the header:
printf 'sha256=%s\n' "$(openssl dgst -sha256 -hmac "$WHSEC" < body.json | awk '{print $NF}')"
The signature covers the body only. It holds no timestamp.
Answer with any 2xx. A delivery that does not get one is tried up to three times, each attempt with a 5-second timeout. If all three fail, the same events are sent again in a later delivery, so a receiver can see an event more than once. Use each event's seq to drop the repeats.
New to vrtmv? Sign up free for 10 migrations, or get a free assessment: run it on one hard host and we review the parity report with you.