<aside> ❗ Notion-Tipp: Nutze diese Seite als ein Beispiel dafür, wie du deine API-Referenz strukturieren und in Notion hosten kannst. Die Endpunkte-Datenbank enthält auch eine Endpunkte-Vorlage für die weitere Dokumentation.

</aside>

Allgemeines

Einleitung

Die Referenz ist der Schlüssel für ein vollständiges Verständnis der Notion-API.

<aside> ❗ Du benötigst ein Integrations-Token, um mit der Notion-API zu interagieren. Du findest ein Integrations-Token, nachdem du eine Integration auf der Seite der Integrationseinstellungen erstellt hast. Wenn du dich zum ersten Mal mit der Notion-API beschäftigst, empfehlen wir dir, mit dem Erste Schritte-Leitfaden zu beginnen, um zu lernen, wie man eine Integration erstellt.

</aside>

Konventionen

Die Grund-URL zum Versenden aller API-Anfragen lautet https://api.notion.com. HTTPS ist für alle API-Anfragen erforderlich.

Die Notion-API folgt, wenn möglich, den RESTful-Konventionen, wobei die meisten Operationen via GET, POST, PATCH, und DELETE Anfragen zu Seiten- oder Datenbankressourcen durchgeführt werden. Anfrage- und Antwortkörper werden als JSON kodiert.

JSON-Konventionen

• Ressourcen der obersten Ebene haben eine "Objekt"-Eigenschaft. Diese Eigenschaft kann verwendet werden, um die Art der Ressource zu bestimmen (z. B. "Datenbank", "Nutzer/-in", etc.)
• Ressourcen der obersten Ebene sind durch eine UUIDv4-"id"-Eigenschaft adressierbar. Du kannst Bindestriche in der ID weglassen, wenn du Anfragen an die API stellst, z. B. wenn du die ID aus einer Notion-URL kopierst.
• Eigenschaftsnamen sind in snake_case (nicht camelCase oder kebab-case).
• Temporäre Werte (Daten und Datenzeitpunkte) sind in ISO 8601-Strings kodiert. Datenzeitpunkte wird den Zeitwert beinhalten (2020-08-12T02:12:33.231Z), während Daten nur das Datum enthalten wird (2020-08-12).
• Die Notion-API unterstützt keine leeren Strings. Um einen String-Wert für Eigenschaften wie z. B. ein urlProperty-Wertobjekt aufzuheben, verwende eine explizite null anstelle von "".

Code-Beispiele & SDKs

Für jeden Endpunkt werden Beispiele für Anfragen und Antworten gezeigt. Die Anfragen werden mit dem Notion [JavaScript SDK] (https://github.com/makenotion/notion-sdk-js) und [cURL] (https://curl.se/) dargestellt. Diese Beispiele erleichtern das Kopieren, Einfügen und Ändern bei der Erstellung deiner Integration.

Die Notion SDKs sind Open-Source-Projekte, die du installieren kannst, um einfach mit der Erstellung zu beginnen. Du kannst auch jede andere Sprache oder Bibliothek wählen, mit der du HTTP-Anfragen stellen kannst.

Paginierung

Endpunkte, die Listen von Objekten zurückgeben, unterstützen cursorbasierte Paginierungsanfragen. Standardmäßig gibt Notion zehn Elemente pro API-Aufruf zurück. Wenn die Anzahl der Elemente in einer Antwort von einem Support-Endpunkt den Standardwert übersteigt, kann eine Integration die Paginierung verwenden, um einen bestimmten Satz von Ergebnissen anzufordern und/oder die Anzahl der zurückgegebenen Elemente zu begrenzen.

UNTERSTÜTZE ENDPUNKTE

ANTWORTEN

Anfragelimits

To ensure a consistent developer experience for all API users, the Notion API is rate limited and basic size limits apply to request parameters.

Ratenbeschränkungen

Ratenbeschränkte Anfragen werden einen "rate_limited"-Fehlercode zurückmelden. (HTTP Antwortstatus 429). Die Ratenbeschränkung für eingehende Anfragen pro Integration liegt bei durchschnittlich drei Anfragen pro Sekunde. Einige Überschreitungen der durchschnittlichen Rate sind erlaubt.

<aside> ❗ Ratenbeschränkungen können sich verändern

Für die Zukunft planen wir, die Ratenbeschränkungen anzupassen, um einen Ausgleich zwischen Nachfrage und Verlässlichkeit zu finden. Wir werden möglicherweise bestimmte Ratenbeschränkungen für Workspaces unterschiedlicher kostenpflichtiger Pläne einführen.

</aside>

Größenbeschränkungen

Notion begrenzt die Größe bestimmter Parameter and the depth of children in requests. Eine Anfrage, die eine dieser Beschränkungen überschreitet, wird einen  "validation_error"-Fehlercode zurückmelden (HTTP Antwortstatus 400) und spezifischere Details in der "message"-Eigenschaft enthalten.

Statuscodes

HTTP-Antwortcodes werden verwendet, um allgemeine Erfolgs- und Fehlerklassen anzugeben

Erfolgscodes

Fehlercodes

Fehlercodes beinhalten weitere Details zum Fehler in den “code” und “message”-Eigenschaften des Antwortkörpers.

Versionen

Unsere API-Versionen sind nach dem Datum benannt, an dem die Version veröffentlicht wurde. Unsere neueste Version ist zum Beispiel 2022-06-28.

Du legst die Version fest, indem du einen Notion-Version-Header einfügst. Das Setzen des Notion-Version-Headers ist erforderlich.

curl <https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5> \\
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns"
  -H "Notion-Version: 2022-06-28"

Objekte

Nutzer/-innen

Wo Benutzerobjekte in der API erscheinen

Benutzerobjekte erscheinen in der API in fast allen Objekten, die von der API zurückgegeben werden, einschließlich:

• Blockobjekt unter erstellt_von  und zuletzt_bearbeitet_von.
• Seitenobjekt unter erstellt_von und zuletzt_bearbeitet_von und in people-Eigenschaftselementen.
• Datenbankobjekt unter erstellt_von und zuletzt_bearbeitet_von.
• Rich text-Objekt, wie vom Nutzer/von der Nutzerin bezeichnet.
• Eigenschaftsobjekt, wenn die Eigenschaft eine people-Eigenschaft ist.

Nutzerobjekte beinhalten immer objekt and id-Schlüssel wie unten beschrieben. Die übrigen Eigenschaften können angezeigt werden, wenn der Benutzer oder die Benutzerin in einem Rich-Text- oder Seiteneigenschaftskontext gerendert wird und der Bot über die richtigen Fähigkeiten für den Zugriff auf diese Eigenschaften verfügt. Weitere Informationen zu Fähigkeiten finden Sie in der Anleitung zu Fähigkeiten und in der Anleitung zur Autorisierung.

Alle Nutzer/-innen

Diese Felder werden zwischen allen Nutzer/-innen geteilt, einschließlich Menschen und Bots. Felder mit einer *-Markierung sind immer präsent.

Datei

Dateiobjekte enthalten Daten über eine Datei, die in Notion hochgeladen wurde, oder Daten über externe Dateien, die in Notion verlinkt sind.

{
  "type": "file",
  "file": {
    "url": "<https://s3.us-west-2.amazonaws.com/secure.notion-static.com/7b8b0713-dbd4-4962-b38b-955b6c49a573/My_test_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221024%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221024T205211Z&X-Amz-Expires=3600&X-Amz-Signature=208aa971577ff05e75e68354e8a9488697288ff3fb3879c2d599433a7625bf90&X-Amz-SignedHeaders=host&x-id=GetObject>",
    "expiry_time": "2022-10-24T22:49:22.765Z"
  }
}

Seiten-, Einbettungs-, Bild-, Video-, Datei-, PDF- und Lesezeichen-Blockarten beinhalten Dateiobjekte. Icon- und Cover-Seitenobjekt-Werte beinhalten ebenfalls Dateiobjekte.

Jedes Dateiobjekt beinhaltet die folgenden Felder:

Endpunkte

Endpoints