Objects

The object model

ObjectSource

ObjectSpace

ObjectNote

ObjectTag

ObjectEmbedding

By default, an object's embedding is an interleaved representation of the object and its attachments — its own content and attached media encoded together. The exact representation may change over time, so treat the vector as opaque rather than depending on a specific encoding.

Actions

List objects

Returns all objects belonging to the authenticated user. Objects outside the access key's content scope are silently omitted from results.

[
  {
    "id": "a1B2c3D4e5F6g7H8i9J0k1",
    "title": "The Art of Plain Text",
    "url": "https://example.com/plain-text",
    "content": {
      "type": "text/markdown",
      "body": "# The Art of Plain Text\n\nPlain text is the most portable, future-proof format..."
    },
    "tags": [
      { "name": "writing" },
      { "name": "tools" }
    ],
    "created": "2024-03-01T12:00:00Z",
    "modified": "2024-03-01T12:00:00Z",
    "bumped": "2024-03-01T12:00:00Z"
  }
]

{"id":"a1B2c3D4e5F6g7H8i9J0k1","title":"The Art of Plain Text",…}
{"id":"z9Y8x7W6v5U4t3S2r1Q0p9","title":"Meeting notes",…}
{"id":"m5N6o7P8q9R0s1T2u3V4w5","title":"Reading list",…}

Create an object

Creates a new object from a URL, inline content, or uploaded file.

{
  "id": "a1B2c3D4e5F6g7H8i9J0k1",
  "title": "Example Article",
  "url": "https://example.com/article",
  "tags": [
    { "name": "reading" }
  ],
  "created": "2024-04-08T09:00:00Z",
  "modified": "2024-04-08T09:00:00Z",
  "bumped": "2024-04-08T09:00:00Z"
}

{
  "id": "a1B2c3D4e5F6g7H8i9J0k1",
  "title": "Example Article",
  "url": "https://example.com/article",
  "tags": [
    { "name": "reading" }
  ],
  "created": "2024-04-08T09:00:00Z",
  "modified": "2024-04-08T09:00:00Z",
  "bumped": "2024-04-08T15:30:00Z"
}

Get an object

Retrieves a single object by its ID.

{
  "id": "a1B2c3D4e5F6g7H8i9J0k1",
  "title": "The Art of Plain Text",
  "url": "https://example.com/plain-text",
  "content": {
    "type": "text/markdown",
    "body": "# The Art of Plain Text\n\nPlain text is the most portable, future-proof format..."
  },
  "tags": [
    { "name": "writing" },
    { "name": "tools" }
  ],
  "created": "2024-03-01T12:00:00Z",
  "modified": "2024-03-01T12:00:00Z",
  "bumped": "2024-03-01T12:00:00Z"
}

Get object blob

Returns the original blob that was uploaded to the object — no transcoded or derived variants. Only works for objects with a single uploaded attachment (e.g. an image, video, or PDF); returns 422 otherwise. The response may be a 302 redirect to a CDN URL, so your client must follow redirects.

<original blob bytes>

Location: https://mymind.media/...

Get object content

Returns the content of a text-based object. Set the Accept header to pick a format, or omit it to receive the content in its native format. Only works for text-based objects (e.g. article, note). Returns 422 for non-text types, and 406 if the requested format isn't supported.

# The Art of Plain Text

Plain text is the most portable, future-proof format for writing...

Get object screenshot

Returns the screenshot captured at save time — typically the rendered view of a saved web page or article. Returns 422 for objects without a screenshot. The response may be a 302 redirect to a CDN URL, so your client must follow redirects.

<screenshot image bytes>

Location: https://mymind.media/...

Get object thumbnail

Returns a thumbnail image for the object. Useful for previews, lists, and grids. Available for any object with a renderable thumbnail (images, videos, articles with cover images, etc.).

<image bytes>

Location: https://mymind.media/...
// signed URL, valid for ~5 minutes

Update an object

Updates an object's metadata. Only include the fields you want to change — omitted fields are left untouched.

{}

Create an object note

Appends a new note to the object's notes array and returns its assigned id. Send Markdown for a simple note, or Prose to preserve rich formatting.

Reminders for later:

- [ ] Follow up with Sam
- [ ] Check on the proofs

{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "Reminders for later:" }]
    },
    {
      "type": "taskList",
      "content": [
        {
          "type": "taskItem",
          "attrs": { "checked": false },
          "content": [
            {
              "type": "paragraph",
              "content": [{ "type": "text", "text": "Follow up with Sam" }]
            }
          ]
        },
        {
          "type": "taskItem",
          "attrs": { "checked": false },
          "content": [
            {
              "type": "paragraph",
              "content": [{ "type": "text", "text": "Check on the proofs" }]
            }
          ]
        }
      ]
    }
  ]
}

{
  "id": "n4K8m2N6p9Q3r5T7v1X0z2"
}

Update an object note

Replaces the body of an existing note. Returns 404 if the note doesn't exist on the object. This is a full replace — not a patch.

{}

Delete an object note

Removes a note from the object's notes array. Idempotent — deleting a note that's already gone is a no-op.

{}

Update object content

Replaces the entire content body of a Note. Returns 422 for any other object type. This is a full replace — not a patch. Send Markdown for a simple rewrite, or Prose to preserve rich formatting.

{}

Add tags to an object

Adds tags to an object.

[
  { "name": "design" },
  { "name": "inspiration" }
]

{}

Remove tags from an object

Removes one or more tags from an object. Tags can be referenced by name or by id — mix and match within the same request. Removing a tag that isn't on the object is a no-op.

[
  { "name": "design" },
  { "name": "inspiration" }
]

[
  { "id": "t8R3p9K2m5N7q1V4x6L0z8" }
]

{}

Add an object to spaces

Adds an object to one or more spaces. Objects may belong to a maximum of 100 spaces.

[
  { "id": "j5K6l7M8n9O0p1Q2r3S4t5" }
]

{}

Pin an object

Pins an object to your top of mind. Pass an optional position in the body to control ordering — omit it to append to the end.

{}

Unpin an object

Removes an object from your top of mind. Idempotent — unpinning an object that isn't pinned is a no-op.

{}

Delete an object

Soft-deletes an object. Deleted objects are recoverable for 30 days, after which they are permanently destroyed.

{}

Restore an object

Restores a deleted object. Objects can be restored within 30 days of deletion.

{}