Build with Phasoric

Public contracts for handoffs, hosted APIs, MCP, automation, partner products, and governed extensions.

supported
View Markdown

Developer REST API

The Developer REST API is mounted at:

/api/dev

It is intended for scripts and backends operating on an explicitly connected Phasoric Hosted vault. It does not expose arbitrary browser-local vaults.

The canonical OpenAPI 3.1 contract is available at GET /api/dev/openapi.json. It is generated from the same REST operation and hosted MCP allowlists enforced by the server; clients should treat undocumented methods and fields as unavailable.

Actual API use requires the Developer entitlement boundary and an authenticated personal access token.

Authentication

Authorization: Bearer bda_…

Vault operations also require an explicit hosted mappingId. Depending on the endpoint you can send it as request data/query or:

X-Phasoric-Mapping: <mapping-uuid>

List notes

GET /api/dev/notes?mappingId=<uuid>

Returns a bounded inventory of hosted Markdown notes with path, title, revision, size, and update time. The current inventory limit is 1,000 notes per request.

Send Accept: text/markdown to supported read endpoints when you want a Markdown representation instead of JSON.

Read one note

Current route shape:

GET /api/dev/notes/:category/:filename?mappingId=<uuid>

The response includes the note content and its current revision. Phasoric also emits the revision as an ETag.

Do not assume the current two-segment read route is a generic wildcard path. Use the route contract actually exposed by your deployment.

Preview or write a note

POST /api/dev/notes
Content-Type: application/json
Idempotency-Key: example-write-42

{
  "mappingId": "<uuid>",
  "path": "Projects/Launch.md",
  "content": "# Launch\n",
  "dryRun": true
}

dryRun defaults to true. To apply the write, explicitly send dryRun: false and an idempotency key.

When replacing an existing note, provide the current expected revision/hash through expectedHash or the supported conditional header. Phasoric should reject a stale update rather than silently overwrite a newer revision.

Delete a note

DELETE /api/dev/notes/:category/:filename?mappingId=<uuid>&dryRun=true
If-Match: <current-revision>
Idempotency-Key: example-delete-42

Deletes use the hosted knowledge transaction boundary and create recoverable hosted trash state before the live note is removed.

Multi-note transactions

POST /api/dev/transactions
Content-Type: application/json
Idempotency-Key: project-update-2026-08-16

{
  "mappingId": "<uuid>",
  "dryRun": true,
  "actions": [
    {
      "type": "write-note",
      "path": "Projects/Launch.md",
      "content": "# Launch\nUpdated plan",
      "expectedHash": "<current-revision>"
    },
    {
      "type": "write-note",
      "path": "Projects/Launch Risks.md",
      "content": "# Risks\n"
    }
  ]
}

Applied actions commit through one hosted database transaction. Use the preview result to verify the intended mutation set before applying it.

Provenance events

GET /api/dev/events?mappingId=<uuid>&since=<cursor>&limit=<n>

The event feed is scoped to the authenticated user and explicit hosted mapping.

Error handling

Treat HTTP status plus stable response code values as the programmatic signal where provided. Do not branch automation on human-readable message text.

Common failure classes include:

  • authentication/entitlement failure;
  • invalid or inaccessible mappingId;
  • invalid note path;
  • stale expected revision;
  • missing idempotency for an applied write;
  • quota/rate boundary;
  • hosted note not found.

Local-first limitation

If the user has not connected the logical vault to Phasoric Hosted, this API cannot read it. Ask the user to configure an appropriate hosted mapping; do not create a shadow upload path in your integration.