💠 GENERIC

INTRODUCTION

This documentation provides a comprehensive guide to understanding and using the Your API REST API.

❗ To interact with the API, you need an API key. You can obtain your API key from the API settings page. If this is your first time using the API, we recommend starting with the Getting Started Guide to learn how to generate an API key and set up your environment.

CONVENTIONS

The base URL for all API requests is https://api.example.com. HTTPS is required for all API interactions.

The API follows RESTful conventions with operations performed using GET, POST, PUT, PATCH, and DELETE requests on various resources. All request and response bodies are encoded as JSON.

JSON CONVENTIONS

• Top-Level Resource Type ("object" Property): Each top-level resource in a JSON response has an "object" property, which indicates the type of the resource. This is useful for determining the nature of the resource being returned. Examples include:

  • "database": Represents a database resource.

  • "page": Represents a page resource.

  • "user": Represents a user resource.

  • "block": Represents a block resource.

• Resource Identification ("id" Property): Resources are uniquely identified by a UUIDv4 "id" property. This ID can be used to reference the resource in subsequent API requests. Note that when making requests, you may omit dashes from the ID if copying it directly from a Notion URL. For example:

  • Full UUID: "123e4567-e89b-12d3-a456-426614174000"

  • Omitted dashes: "123e4567e89b12d3a456426614174000"

• Property Naming (snake_case): Property names within the JSON responses are formatted using snake_case. This convention is consistent across different types of resources. For example:

  • "created_time": Represents the creation time of a resource.

  • "last_edited_by": Represents the user who last edited the resource.

  • "page_id": Represents the ID of a page.

• Temporal Values (ISO 8601 Encoding): Temporal values, such as dates and datetimes, are encoded using the ISO 8601 standard. This ensures a consistent and clear format for timestamps:

  • Datetime: Includes both date and time, with the format YYYY-MM-DDTHH:MM:SS.sssZ. Example: "2024-09-16T14:45:30.000Z"

  • Date: Includes only the date, with the format YYYY-MM-DD. Example: "2024-09-16"

• Handling Empty Strings: The API does not support empty strings for certain properties. Instead of using an empty string ("") to represent a lack of value, you should use null to explicitly indicate that the value is unset. This applies to properties like URLs or rich text fields:

  • Invalid: "url": ""

  • Valid: "url": null

CODE SAMPLES AND SDK

Request samples are provided for each endpoint using common tools like cURL and code snippets in popular SDKs. You can also use any HTTP client library of your choice.

Sample using cURL:

curl -X GET "https://api.example.com/users"   -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sample using JavaScript SDK:

const exampleSDK = require('example-sdk');

exampleSDK.users.getAllUsers()
  .then(response => console.log(response))
  .catch(error => console.error(error));

SDKs: Check our SDK repository for various language-specific implementations.

SUPPORTED ENDPOINTS

RESPONSES

REQUEST LIMITS

To ensure fair usage and maintain performance, the API enforces rate and size limits on requests.

RATE LIMITS

The API imposes rate limits to prevent abuse and ensure equitable access.

• Rate Limit: The average rate limit is 5 requests per second per user.

• Exceeding Limits: If you exceed the rate limits, the API will return a 429 Rate Limit Exceeded error.

❗ Rate Limits May Change

The rate limits may be adjusted based on system demand and performance metrics.

SIZE LIMITS

STATUS CODE

SUCCESS CODE

ERROR CODES

VERSIONING

API versioning ensures that you can maintain compatibility with the API as it evolves.

Current Version

Format: YYYY-MM-DD

Example: The current API version is 2024-09-16.

Specifying the API Version

To ensure that your requests use a specific version of the API, include the API-Version header in your request.

Example Request:

curl -X GET "https://api.example.com/users"   -H "Authorization: Bearer YOUR_ACCESS_TOKEN"   -H "API-Version: 2024-09-16"

Headers

• Authorization: Include your API access token in the Authorization header for authenticated requests.

• API-Version: Specify the desired API version in the API-Version header to ensure compatibility with your application.

By following these guidelines, you can manage API updates and maintain stability in your integration.

OBJECTS

USERS

User objects represent users within the API. These objects are used in various API responses to provide details about the user involved in different actions.

WHERE USER OBJECT APPEARS

• Posts: In the created_by and last_edited_by fields, indicating the user who created or last edited the post.

• Comments: In the creator and modifier fields, showing the user who created or modified the comment.

USER FIELDS

POST

Post objects represent individual posts within the API. They provide detailed information about specific posts.

POST FIELDS

FILE

File objects provide metadata for files within the API. They are used to describe file details and access information.

FILE FIELDS