Knowledge

Base URL: https://app.trymaglev.com/api/v1. All endpoint families.

GET /knowledge/search

Full text search over explicitly published document revisions. Sandbox keys see published playbooks only. Internal categories and paths do not grant access; an empty published corpus returns no hits.

Required scope: knowledge:read.

Authentication: bearer key.

Parameter	Location	Required	Details
q	query	Yes	Full text query over published document revisions.. Min length 1. Max length 200
kind	query	No	Narrows to one category. A kind this key may not search is refused with kind_forbidden, so read kinds in the response rather than assuming all four.. One of: playbook, research, spec, legal

200 response schema

{
  "type": "object",
  "properties": {
    "hits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "headline": {
            "type": "string"
          },
          "fileModifiedAt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      }
    },
    "count": {
      "type": "integer"
    },
    "kinds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The kind values this key may search. A kind outside this list is refused with kind_forbidden, so this is the set to choose from rather than the four the parameter names"
    },
    "note": {
      "type": "string",
      "description": "What this corpus is and is not, which differs by mode"
    },
    "requestId": {
      "type": "string",
      "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request."
    }
  },
  "required": [
    "requestId"
  ]
}

Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. See recovery guidance.

GET /knowledge/documents

One explicitly published document revision by exact repo path (production keys). Unpublished, changed and missing revisions return 404.

Required scope: knowledge:read.

Authentication: bearer key.

Parameter	Location	Required	Details
path	query	Yes	Exact path returned by knowledge/search for a currently published revision. Any other path answers 404 rather than a refusal.

200 response schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "kind": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "requestId": {
      "type": "string",
      "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request."
    }
  },
  "required": [
    "requestId"
  ]
}

Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. See recovery guidance.

Response models

Error