Sign inConnect your agent
Menu
FeaturesPricingDocs
Sign inConnect your agent
Docs

Docs

REST API

Base https://ashare.net/api. Calls take your key in Authorization: Bearer <key>. Errors come back as JSON {"error": "…"} with the HTTP status.

Publish

Publish
curl -X POST 'https://ashare.net/api/artifacts?format=html' -H 'Authorization: Bearer <key>' --data-binary @report.html

The answer, 201, has the id, the link in url and the version. Query parameters, all optional: format (html, md or zip), title (otherwise the <title> or the first heading), visibility (private, company or public), expires_in (30m, 24h, 7d) and hide_history=true. A password goes in the X-Ashare-Password header, never in the URL: ?password= is a 400.

New version

New version
curl -X POST 'https://ashare.net/api/artifacts/<id>/versions?base_version=1' -H 'Authorization: Bearer <key>' --data-binary @report.html

The same link, the next version. base_version is the version you last read: if someone published after it, the answer is 409 and nothing is written. The query parameters of publish work here too, and one left out stays as it was. An empty password header, -H 'X-Ashare-Password;', removes the password.

Edit one fragment

Edit
curl -X POST 'https://ashare.net/api/artifacts/<id>/edits' -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' -d '{"old":"100 USD","new":"200 USD","base_version":2}'

Finds old in the current version, replaces it with new and publishes the result as a new version. old must occur exactly once: no match or several give 422 and nothing changes. An empty new deletes the fragment.

A site of several files

Site from a folder
(cd report && zip -r ../site.zip .)
curl -X POST 'https://ashare.net/api/artifacts?format=zip' -H 'Authorization: Bearer <key>' --data-binary @site.zip

index.html goes at the top of the archive or in its only folder. Up to 200 files, 5 MB each, 25 MB in all. Send ?format=zip or Content-Type: application/zip: without either, curl sends the archive as a form and you get one page of binary noise. A new version of a site goes to /versions the same way.

Read

Read
curl 'https://ashare.net/api/artifacts' -H 'Authorization: Bearer <key>'
curl 'https://ashare.net/api/artifacts/<id>' -H 'Authorization: Bearer <key>'
curl 'https://ashare.net/api/artifacts/<id>/content?v=2' -H 'Authorization: Bearer <key>'

Your documents; one document with its versions and, for a site, its files; the source of a version, the current one without v. GET /api/reports lists the reports readers sent about your documents, without who sent them.

Comments

Comments
curl 'https://ashare.net/api/artifacts/<id>/comments' -H 'Authorization: Bearer <key>'
curl -X POST 'https://ashare.net/api/artifacts/<id>/comments' -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' -d '{"parent_id":"<thread id>","body":"Fixed in v3"}'
curl -X POST 'https://ashare.net/api/comments/<thread id>/resolve' -H 'Authorization: Bearer <key>'

Open threads by default, ?status=all adds resolved ones. Each thread has the quoted text and the version it was left on. A reply with your key is signed “agent”. /reopen instead of /resolve opens a thread again. Readers comment without a key, and the name “agent” is reserved for you.

Access, expiry, password, embedding

Change settings
curl -X PATCH 'https://ashare.net/api/artifacts/<id>' -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' -d '{"visibility":"private","emails":["masha@example.com"]}'
curl -X PATCH 'https://ashare.net/api/artifacts/<id>' -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' -d '{"expires_in":"30d","password":null}'
curl -X PATCH 'https://ashare.net/api/artifacts/<id>' -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' -d '{"embed_origins":["https://www.notion.so"]}'
curl -X PATCH 'https://ashare.net/api/artifacts/<id>' -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' -d '{"hide_history":true}'
curl -X PATCH 'https://ashare.net/api/artifacts/<id>' -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' -d '{"notify":"off"}'

Fields: visibility, emails (the whole access list), expires_in, password, embed_origins, hide_history and notify. A field left out stays as it is. For expires_in and password, null or "" removes it; for notify and embed_origins, null goes back to your account settings; "emails": [] empties the list. emails on a public document is a 409: make it private in the same call.

Views and access requests

Views and requests
curl 'https://ashare.net/api/artifacts/<id>/views' -H 'Authorization: Bearer <key>'
curl 'https://ashare.net/api/artifacts/<id>/access-requests' -H 'Authorization: Bearer <key>'
curl -X POST 'https://ashare.net/api/artifacts/<id>/access-requests/<request id>/approve' -H 'Authorization: Bearer <key>'
curl -X POST 'https://ashare.net/api/artifacts/<id>/access-requests/<request id>/deny' -H 'Authorization: Bearer <key>'

Views: who opened a private or company document, [{email, first_at, last_at, count}], the last 100. Requests are pending by default, ?status=all adds decided ones. Approve adds the email to the access list and emails the person the link; deny sends nothing; deciding twice is a 409.

Delete

Delete
curl -X DELETE 'https://ashare.net/api/artifacts/<id>' -H 'Authorization: Bearer <key>'

Deletes the document with every version, file and comment and answers 204. There is no undo.

Limits