Notebook

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
GET
POST
POST
GET
POST
POST
POST
GET
GET
GET

List all reusable widgets

Required API key scopes

notebook:read

Query parameters

  • limit
    integer
  • offset
    integer
  • search
    string

Response


Example request

GET /api/projects/:project_id/notebook_widgets
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "publication_status": "published",
      "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
      "version_count": 0,
      "instance_count": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "published_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "count": 0,
  "next_offset": 0
}

Retrieve reusable widgets

Required API key scopes

notebook:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/notebook_widgets/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "publication_status": "published",
  "current_version": {
    "generation_cost_usd": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "title": "string",
    "version": 0,
    "operation": "initial",
    "model": "string",
    "artifact_url": "http://example.com",
    "build_status": "queued",
    "build_hash": "string",
    "frame_names": [
      "string"
    ],
    "input_contract": [
      {
        "slot": "string",
        "sourceName": "string",
        "columns": [
          {
            "name": "string",
            "type": "string"
          }
        ],
        "schemaHash": "string"
      }
    ],
    "security_review": {
      "severity": "none",
      "summary": "string",
      "findings": [
        {
          "severity": "low",
          "title": "string",
          "details": "string"
        }
      ],
      "model": "string",
      "review_version": "string",
      "reviewed_at": "2019-08-24T14:15:22Z"
    },
    "has_demo_data": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "pending_version": {
    "generation_cost_usd": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "title": "string",
    "version": 0,
    "operation": "initial",
    "model": "string",
    "artifact_url": "http://example.com",
    "build_status": "queued",
    "build_hash": "string",
    "frame_names": [
      "string"
    ],
    "input_contract": [
      {
        "slot": "string",
        "sourceName": "string",
        "columns": [
          {
            "name": "string",
            "type": "string"
          }
        ],
        "schemaHash": "string"
      }
    ],
    "security_review": {
      "severity": "none",
      "summary": "string",
      "findings": [
        {
          "severity": "low",
          "title": "string",
          "details": "string"
        }
      ],
      "model": "string",
      "review_version": "string",
      "reviewed_at": "2019-08-24T14:15:22Z"
    },
    "has_demo_data": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "version_count": 0,
  "instance_count": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "published_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
Status 404
RESPONSE
{
  "code": "string",
  "detail": "string"
}

Create reusable widgets update demo

Required API key scopes

notebook:writequery:read

Path parameters

  • id
    string

Request parameters

  • version_id
    string
  • frame_name
    string
  • rows
    array

Response


Example request

POST /api/projects/:project_id/notebook_widgets/:id/demo-data
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/:id/demo-data/\
	-d version_id="string",\
	-d frame_name="string",\
	-d rows="array"

Example response

Status 200
RESPONSE
{
  "name": "string",
  "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  "columns": [
    {
      "name": "string",
      "type": "string"
    }
  ],
  "rows": [
    [
      null
    ]
  ],
  "totalRowCount": 0,
  "includedRowCount": 0,
  "offset": 0,
  "nextOffset": 0,
  "truncated": true
}
Status 400
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 404
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 409
RESPONSE
{
  "code": "string",
  "detail": "string"
}

Create reusable widgets discard

Required API key scopes

notebook:write

Path parameters

  • id
    string

Request parameters

  • pending_version_id
    string
  • expected_current_version_id
    string

Response


Example request

POST /api/projects/:project_id/notebook_widgets/:id/discard-version
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/:id/discard-version/\
	-d pending_version_id="string",\
	-d expected_current_version_id="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "publication_status": "published",
  "current_version": {
    "generation_cost_usd": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "title": "string",
    "version": 0,
    "operation": "initial",
    "model": "string",
    "artifact_url": "http://example.com",
    "build_status": "queued",
    "build_hash": "string",
    "frame_names": [
      "string"
    ],
    "input_contract": [
      {
        "slot": "string",
        "sourceName": "string",
        "columns": [
          {
            "name": "string",
            "type": "string"
          }
        ],
        "schemaHash": "string"
      }
    ],
    "security_review": {
      "severity": "none",
      "summary": "string",
      "findings": [
        {
          "severity": "low",
          "title": "string",
          "details": "string"
        }
      ],
      "model": "string",
      "review_version": "string",
      "reviewed_at": "2019-08-24T14:15:22Z"
    },
    "has_demo_data": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "pending_version": {
    "generation_cost_usd": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "title": "string",
    "version": 0,
    "operation": "initial",
    "model": "string",
    "artifact_url": "http://example.com",
    "build_status": "queued",
    "build_hash": "string",
    "frame_names": [
      "string"
    ],
    "input_contract": [
      {
        "slot": "string",
        "sourceName": "string",
        "columns": [
          {
            "name": "string",
            "type": "string"
          }
        ],
        "schemaHash": "string"
      }
    ],
    "security_review": {
      "severity": "none",
      "summary": "string",
      "findings": [
        {
          "severity": "low",
          "title": "string",
          "details": "string"
        }
      ],
      "model": "string",
      "review_version": "string",
      "reviewed_at": "2019-08-24T14:15:22Z"
    },
    "has_demo_data": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "version_count": 0,
  "instance_count": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "published_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
Status 404
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 409
RESPONSE
{
  "code": "string",
  "detail": "string"
}

Retrieve reusable widgets demo

Required API key scopes

notebook:readquery:read

Path parameters

  • frame_name
    string
  • id
    string

Query parameters

  • version_id
    string

Response


Example request

GET /api/projects/:project_id/notebook_widgets/:id/frames/:frame_name
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/:id/frames/:frame_name/

Example response

Status 200
RESPONSE
{
  "name": "string",
  "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  "columns": [
    {
      "name": "string",
      "type": "string"
    }
  ],
  "rows": [
    [
      null
    ]
  ],
  "totalRowCount": 0,
  "includedRowCount": 0,
  "offset": 0,
  "nextOffset": 0,
  "truncated": true
}
Status 404
RESPONSE
{
  "code": "string",
  "detail": "string"
}

Create reusable widgets

Required API key scopes

notebook:write

Path parameters

  • id
    string

Request parameters

  • prompt
    string
  • generation_id
    string
  • model
    Default: claude-sonnet-5
  • generation_operation
    Default: regenerate
  • expected_current_version_id
    string

Response


Example request

POST /api/projects/:project_id/notebook_widgets/:id/generate
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/:id/generate/\
	-d prompt="string",\
	-d generation_id="string"

Example response

Status 202
RESPONSE
{
  "lifecycle_status": "awaiting_generation",
  "error_detail": "string",
  "error_code": "string",
  "failure_phase": "generating_source",
  "artifact_url": "http://example.com",
  "frame_names": [
    "string"
  ],
  "input_bindings": {
    "property1": {
      "source": "string",
      "hog": "string"
    },
    "property2": {
      "source": "string",
      "hog": "string"
    }
  },
  "input_contract": [
    {
      "slot": "string",
      "sourceName": "string",
      "columns": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "schemaHash": "string"
    }
  ],
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "pinned_version_id": "acdd174b-fedb-4cc2-a413-d2bf36fbaf58",
  "widget_id": "917f3fdb-2905-481f-8ff6-04c0fb7d466c",
  "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366",
  "has_versions": true,
  "active_job": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "queued",
    "phase": "string",
    "model": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "started_at": "2019-08-24T14:15:22Z"
  },
  "security_review": {
    "severity": "none",
    "summary": "string",
    "findings": [
      {
        "severity": "low",
        "title": "string",
        "details": "string"
      }
    ],
    "model": "string",
    "review_version": "string",
    "reviewed_at": "2019-08-24T14:15:22Z"
  },
  "is_reusable": true,
  "build_hash": "string"
}
Status 400
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 403
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 404
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 409
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 429
RESPONSE
{
  "code": "string",
  "detail": "string"
}

Create reusable widgets

Required API key scopes

notebook:write

Path parameters

  • id
    string

Request parameters

  • version_id
    string
  • expected_current_version_id
    string

Response


Example request

POST /api/projects/:project_id/notebook_widgets/:id/restore
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/:id/restore/\
	-d version_id="string",\
	-d expected_current_version_id="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "publication_status": "published",
  "current_version": {
    "generation_cost_usd": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "title": "string",
    "version": 0,
    "operation": "initial",
    "model": "string",
    "artifact_url": "http://example.com",
    "build_status": "queued",
    "build_hash": "string",
    "frame_names": [
      "string"
    ],
    "input_contract": [
      {
        "slot": "string",
        "sourceName": "string",
        "columns": [
          {
            "name": "string",
            "type": "string"
          }
        ],
        "schemaHash": "string"
      }
    ],
    "security_review": {
      "severity": "none",
      "summary": "string",
      "findings": [
        {
          "severity": "low",
          "title": "string",
          "details": "string"
        }
      ],
      "model": "string",
      "review_version": "string",
      "reviewed_at": "2019-08-24T14:15:22Z"
    },
    "has_demo_data": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "pending_version": {
    "generation_cost_usd": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "title": "string",
    "version": 0,
    "operation": "initial",
    "model": "string",
    "artifact_url": "http://example.com",
    "build_status": "queued",
    "build_hash": "string",
    "frame_names": [
      "string"
    ],
    "input_contract": [
      {
        "slot": "string",
        "sourceName": "string",
        "columns": [
          {
            "name": "string",
            "type": "string"
          }
        ],
        "schemaHash": "string"
      }
    ],
    "security_review": {
      "severity": "none",
      "summary": "string",
      "findings": [
        {
          "severity": "low",
          "title": "string",
          "details": "string"
        }
      ],
      "model": "string",
      "review_version": "string",
      "reviewed_at": "2019-08-24T14:15:22Z"
    },
    "has_demo_data": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "version_count": 0,
  "instance_count": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "published_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
Status 400
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 404
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 409
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 429
RESPONSE
{
  "code": "string",
  "detail": "string"
}

Create reusable widgets save

Required API key scopes

notebook:write

Path parameters

  • id
    string

Request parameters

  • pending_version_id
    string
  • expected_current_version_id
    string

Response


Example request

POST /api/projects/:project_id/notebook_widgets/:id/save-version
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/:id/save-version/\
	-d pending_version_id="string",\
	-d expected_current_version_id="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "publication_status": "published",
  "current_version": {
    "generation_cost_usd": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "title": "string",
    "version": 0,
    "operation": "initial",
    "model": "string",
    "artifact_url": "http://example.com",
    "build_status": "queued",
    "build_hash": "string",
    "frame_names": [
      "string"
    ],
    "input_contract": [
      {
        "slot": "string",
        "sourceName": "string",
        "columns": [
          {
            "name": "string",
            "type": "string"
          }
        ],
        "schemaHash": "string"
      }
    ],
    "security_review": {
      "severity": "none",
      "summary": "string",
      "findings": [
        {
          "severity": "low",
          "title": "string",
          "details": "string"
        }
      ],
      "model": "string",
      "review_version": "string",
      "reviewed_at": "2019-08-24T14:15:22Z"
    },
    "has_demo_data": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "pending_version": {
    "generation_cost_usd": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "title": "string",
    "version": 0,
    "operation": "initial",
    "model": "string",
    "artifact_url": "http://example.com",
    "build_status": "queued",
    "build_hash": "string",
    "frame_names": [
      "string"
    ],
    "input_contract": [
      {
        "slot": "string",
        "sourceName": "string",
        "columns": [
          {
            "name": "string",
            "type": "string"
          }
        ],
        "schemaHash": "string"
      }
    ],
    "security_review": {
      "severity": "none",
      "summary": "string",
      "findings": [
        {
          "severity": "low",
          "title": "string",
          "details": "string"
        }
      ],
      "model": "string",
      "review_version": "string",
      "reviewed_at": "2019-08-24T14:15:22Z"
    },
    "has_demo_data": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "version_count": 0,
  "instance_count": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "published_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
Status 400
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 404
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 409
RESPONSE
{
  "code": "string",
  "detail": "string"
}

Retrieve reusable widgets

Required API key scopes

notebook:read

Path parameters

  • id
    string

Query parameters

  • version_id
    string

Response


Example request

GET /api/projects/:project_id/notebook_widgets/:id/source
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/:id/source/

Example response

Status 200
RESPONSE
{
  "source": "string"
}
Status 400
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 404
RESPONSE
{
  "code": "string",
  "detail": "string"
}

Retrieve reusable widgets

Required API key scopes

notebook:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/notebook_widgets/:id/status
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/:id/status/

Example response

Status 200
RESPONSE
{
  "lifecycle_status": "awaiting_generation",
  "error_detail": "string",
  "error_code": "string",
  "failure_phase": "generating_source",
  "artifact_url": "http://example.com",
  "frame_names": [
    "string"
  ],
  "input_bindings": {
    "property1": {
      "source": "string",
      "hog": "string"
    },
    "property2": {
      "source": "string",
      "hog": "string"
    }
  },
  "input_contract": [
    {
      "slot": "string",
      "sourceName": "string",
      "columns": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "schemaHash": "string"
    }
  ],
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "pinned_version_id": "acdd174b-fedb-4cc2-a413-d2bf36fbaf58",
  "widget_id": "917f3fdb-2905-481f-8ff6-04c0fb7d466c",
  "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366",
  "has_versions": true,
  "active_job": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "queued",
    "phase": "string",
    "model": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "started_at": "2019-08-24T14:15:22Z"
  },
  "security_review": {
    "severity": "none",
    "summary": "string",
    "findings": [
      {
        "severity": "low",
        "title": "string",
        "details": "string"
      }
    ],
    "model": "string",
    "review_version": "string",
    "reviewed_at": "2019-08-24T14:15:22Z"
  },
  "is_reusable": true,
  "build_hash": "string"
}
Status 404
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 409
RESPONSE
{
  "code": "string",
  "detail": "string"
}

Retrieve reusable widgets

Required API key scopes

notebook:read

Path parameters

  • id
    string

Query parameters

  • limit
    integer
    Default: 25
  • offset
    integer
    Default: 0

Response


Example request

GET /api/projects/:project_id/notebook_widgets/:id/versions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebook_widgets/:id/versions/

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "generation_cost_usd": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "title": "string",
      "version": 0,
      "operation": "initial",
      "model": "string",
      "artifact_url": "http://example.com",
      "build_status": "queued",
      "build_hash": "string",
      "frame_names": [
        "string"
      ],
      "input_contract": [
        {
          "slot": "string",
          "sourceName": "string",
          "columns": [
            {
              "name": "string",
              "type": "string"
            }
          ],
          "schemaHash": "string"
        }
      ],
      "security_review": {
        "severity": "none",
        "summary": "string",
        "findings": [
          {
            "severity": "low",
            "title": "string",
            "details": "string"
          }
        ],
        "model": "string",
        "review_version": "string",
        "reviewed_at": "2019-08-24T14:15:22Z"
      },
      "has_demo_data": true,
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "count": 0,
  "next_offset": 0
}
Status 400
RESPONSE
{
  "code": "string",
  "detail": "string"
}
Status 404
RESPONSE
{
  "code": "string",
  "detail": "string"
}