Motif API

An introductory guide to querying the Motif API.

The Motif Platform API gives you programmatic access to you project data in various forms, such as raw content or JS bundles, via a simple HTTP endpoint.

Authentication

With the exception of the pages endpoint, API requests must provide a bearer token in the Authorization header:

Authorization: Bearer <TOKEN>

To obtain a token, head over to the space settings, select the "Development" tab, and hit "Create token".

Your tokens can perform API requests to your space's projects and pages without restrictions. Make sure to keep your tokens confidential and only store them on your own servers. Do not share your tokens with third parties. If you believe a token has been compromised, you can revoke it at any time.

Encoding

With the exception of the pages endpoint, API requests must be encoded with the Content-Type: application/json header. Responses are likewise encoded as JSON. For the pages endpoint, the response is an ES module, and the response type is application/javascript.

Endpoints

Projects

Get projects

Endpoint
GET /v1/projects

Get a list of the projects under your space.

Example request
curl "https://api.motif.land/v1/projects" \
  -H "Authorization: Bearer <TOKEN>"
Example response
{
  "data": {
    "projects": [
      {
        "id": "588225479998964038",
        "name": "A project name",
        "domain": "a-project-domain",
        "spaceId": "829599843919566672"
      },
      {
        "id": "878977683429979945",
        "name": "Another project name",
        "domain": "another-project-domain",
        "spaceId": "829599843919566672"
      }
    ]
  }
}

Get project data

Endpoint
GET /v1/projects/:id

Get the information for a single project, including all files and folders.

Example request
curl "https://api.motif.land/v1/projects/a-project-id" \
  -H "Authorization: Bearer <TOKEN>"
Example response
{
  "data": {
    "id": "306116510530667073",
    "files": [
      {
        "id": "306116511297176129",
        "updatedAt": 1628197589450,
        "name": "motif.json",
        "isPublic": null,
        "parent": "",
        "meta": {},
        "fileType": "json"
      },
      {
        "id": "306116511297177153",
        "updatedAt": null,
        "name": "tailwind.config.js",
        "isPublic": null,
        "parent": "",
        "meta": {},
        "fileType": "js"
      },
      {
        "id": "306116511297178177",
        "updatedAt": null,
        "name": "main.css",
        "isPublic": null,
        "parent": "306116511023500865",
        "meta": {},
        "fileType": "css"
      },
      {
        "id": "306116511297185345",
        "updatedAt": 1628208302402,
        "name": "Index",
        "isPublic": null,
        "parent": "306116511023499841",
        "meta": {
          "title": "Motif",
          "date": "2021-08-05"
        },
        "fileType": "mdx"
      }
    ],
    "folders": [
      {
        "id": "306116511023497793",
        "updatedAt": null,
        "name": "components",
        "projectId": "306116510530667073",
        "parent": ""
      },
      {
        "id": "306116511023498817",
        "updatedAt": null,
        "name": "templates",
        "projectId": "306116510530667073",
        "parent": ""
      },
      {
        "id": "306116511023499841",
        "updatedAt": null,
        "name": "pages",
        "projectId": "306116510530667073",
        "parent": ""
      },
      {
        "id": "306116511023500865",
        "updatedAt": null,
        "name": "styles",
        "projectId": "306116510530667073",
        "parent": ""
      }
    ]
  }
}

Pages

These endpoints do not require authentication.

Get page source

Endpoint
GET /v1/exports/raw/:id

Get the raw page source.

Example request
curl "https://api.motif.land/v1/exports/raw/a-page-id"
Example response
---
title: Motif
date: 2023-07-01
---

Welcome to Motif!

Get page as ES module (MDX)

Endpoint
GET /v1/exports/esm/:id

Get a page as an ES module.

Example request
curl "https://api.motif.land/v1/exports/esm/a-page-id"
Example response
import React from "https://cdn.skypack.dev/react"

export const _meta = {
  title: "Motif",
  date: "2023-07-01",
}

function MDXContent(props) {
  const _components = Object.assign(
      {
        p: "p",
      },
      props.components
    ),
    { wrapper: MDXLayout } = _components

  const _content = /*#__PURE__*/ React.createElement(
    React.Fragment,
    null,
    /*#__PURE__*/ React.createElement(_components.p, null, "Welcome to Motif!")
  )

  return MDXLayout
    ? /*#__PURE__*/ React.createElement(MDXLayout, props, _content)
    : _content
}

export default MDXContent
let __meta = {}

if (typeof _meta !== "undefined") {
  __meta = { ...__meta, ..._meta }
}

export const meta = __meta
export const filename = "index"

This endpoint is intended to be used for ES module imports. So using the same URL, you can embed page content into your existing JavaScript projects. For instance:

import Page, { meta } from "https://api.motif.land/v1/pages/esm/a-page-id"

const Component = () => {
  console.log("Meta", JSON.stringify(meta))
  return <Page />
}

export default Component

Get Markdoc AST (Markdoc only)

Endpoint
GET /v1/exports/markdoc/ast/:id

Get the AST associated to a Markdoc page.

Example request
curl "https://api.motif.land/v1/exports/markdoc/ast/a-page-id"
Example response
{
  "$$mdtype": "Node",
  "errors": [],
  "lines": [],
  "inline": false,
  "attributes": { "frontmatter": "title: Motif\ndate: 2023-07-01" },
  "children": [
    {
      "$$mdtype": "Node",
      "errors": [],
      "lines": [5, 6],
      "inline": false,
      "attributes": {},
      "children": [
        {
          "$$mdtype": "Node",
          "errors": [],
          "lines": [5, 6],
          "inline": false,
          "attributes": {},
          "children": [
            {
              "$$mdtype": "Node",
              "errors": [],
              "lines": [5, 6],
              "inline": true,
              "attributes": { "content": "Welcome to Motif!" },
              "children": [],
              "type": "text",
              "location": { "start": { "line": 5 }, "end": { "line": 6 } }
            }
          ],
          "type": "inline",
          "location": { "start": { "line": 5 }, "end": { "line": 6 } }
        }
      ],
      "type": "paragraph",
      "location": { "start": { "line": 5 }, "end": { "line": 6 } }
    }
  ],
  "type": "document"
}