Skip to content

Create a notebook

post/v2/projects/{ref}/notebooks

Creates a notebook shared with everyone who has access to the project. Cell ids are assigned by the server and returned in the response.

OAuth scopes

  • database:write

The fine-grained token must include the following permissions to access this endpoint:

  • project_notebooks_write

Path parameters

  • ref
    Required
    string

    Project ref

Body

  • data
    Required
    object

Response codes

  • 201
  • 400
  • 401
  • 403
  • 429
  • 500

Response (201)

{
  "data": {
    "type": "notebook",
    "id": "lorem",
    "attributes": {
      "name": "lorem",
      "description": "lorem",
      "favorite": true,
      "inserted_at": "lorem",
      "updated_at": "lorem",
      "owner": {
        "id": 42,
        "username": "lorem"
      },
      "updated_by": {
        "id": 42,
        "username": "lorem"
      },
      "content": {
        "schema_version": 42,
        "cells": [
          {
            "id": "lorem",
            "type": "markdown",
            "text": "lorem"
          }
        ]
      }
    }
  }
}
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Resource type.",
          "enum": [
            "notebook"
          ]
        },
        "id": {
          "type": "string"
        },
        "attributes": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string",
              "nullable": true
            },
            "favorite": {
              "type": "boolean"
            },
            "inserted_at": {
              "type": "string"
            },
            "updated_at": {
              "type": "string"
            },
            "owner": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "number"
                },
                "username": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "username"
              ],
              "description": "User who created the notebook.",
              "nullable": true
            },
            "updated_by": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "number"
                },
                "username": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "username"
              ],
              "description": "User who last wrote to the notebook.",
              "nullable": true
            },
            "content": {
              "type": "object",
              "properties": {
                "schema_version": {
                  "type": "number"
                },
                "cells": {
                  "type": "array",
                  "items": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "markdown"
                            ]
                          },
                          "text": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "type",
                          "text"
                        ]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "database"
                            ]
                          },
                          "sql": {
                            "type": "string",
                            "description": "SQL run against the project database."
                          },
                          "row_limit": {
                            "default": 100,
                            "type": "integer",
                            "exclusiveMinimum": true,
                            "maximum": 9007199254740991,
                            "minimum": 0
                          },
                          "database_identifier": {
                            "description": "Read replica to run against. Omit to use the primary database.",
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "view": {
                            "type": "string",
                            "enum": [
                              "table",
                              "chart"
                            ]
                          },
                          "chart": {
                            "description": "Chart configuration, retained even while `view` is `table`.",
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "bar",
                                  "line"
                                ]
                              },
                              "x_column": {
                                "type": "string",
                                "description": "Result column used for the x axis."
                              },
                              "y_series": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "column": {
                                      "type": "string",
                                      "description": "Result column plotted as a series."
                                    }
                                  },
                                  "required": [
                                    "column"
                                  ]
                                }
                              },
                              "scale": {
                                "type": "string",
                                "enum": [
                                  "linear",
                                  "log"
                                ]
                              },
                              "cumulative": {
                                "type": "boolean"
                              },
                              "show_labels": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "type",
                              "x_column",
                              "y_series",
                              "scale",
                              "cumulative",
                              "show_labels"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "type",
                          "sql",
                          "row_limit"
                        ]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "log"
                            ]
                          },
                          "sql": {
                            "type": "string",
                            "description": "SQL run against the project logs."
                          },
                          "time_range": {
                            "oneOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "absolute"
                                    ]
                                  },
                                  "start": {
                                    "type": "string",
                                    "description": "ISO 8601 start of the range."
                                  },
                                  "end": {
                                    "type": "string",
                                    "description": "ISO 8601 end of the range."
                                  }
                                },
                                "required": [
                                  "type",
                                  "start",
                                  "end"
                                ]
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "relative"
                                    ]
                                  },
                                  "unit": {
                                    "type": "string",
                                    "enum": [
                                      "minute",
                                      "hour",
                                      "day",
                                      "week",
                                      "month",
                                      "year"
                                    ]
                                  },
                                  "amount": {
                                    "type": "integer",
                                    "exclusiveMinimum": true,
                                    "maximum": 9007199254740991,
                                    "minimum": 0
                                  }
                                },
                                "required": [
                                  "type",
                                  "unit",
                                  "amount"
                                ]
                              }
                            ]
                          },
                          "title": {
                            "type": "string"
                          },
                          "view": {
                            "type": "string",
                            "enum": [
                              "table",
                              "chart"
                            ]
                          },
                          "chart": {
                            "description": "Chart configuration, retained even while `view` is `table`.",
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "bar",
                                  "line"
                                ]
                              },
                              "x_column": {
                                "type": "string",
                                "description": "Result column used for the x axis."
                              },
                              "y_series": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "column": {
                                      "type": "string",
                                      "description": "Result column plotted as a series."
                                    }
                                  },
                                  "required": [
                                    "column"
                                  ]
                                }
                              },
                              "scale": {
                                "type": "string",
                                "enum": [
                                  "linear",
                                  "log"
                                ]
                              },
                              "cumulative": {
                                "type": "boolean"
                              },
                              "show_labels": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "type",
                              "x_column",
                              "y_series",
                              "scale",
                              "cumulative",
                              "show_labels"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "type",
                          "sql",
                          "time_range"
                        ]
                      }
                    ]
                  }
                }
              },
              "required": [
                "schema_version",
                "cells"
              ]
            }
          },
          "required": [
            "name",
            "description",
            "favorite",
            "inserted_at",
            "updated_at",
            "owner",
            "updated_by",
            "content"
          ]
        }
      },
      "required": [
        "type",
        "id",
        "attributes"
      ]
    }
  },
  "required": [
    "data"
  ]
}