Objects

The object model

ObjectSource

ObjectSpace

ObjectNote

ObjectTag

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.

{
  "tags": [
    { "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.

{}