Google Notebooks API
Browse all Google APIs40
AI ReadinessFoundational (D-)40/100
Official vendor OpenAPI document · agent-readyAI/MLMl Inferenceoauth223 EndpointsREST
For Agents
Provision and manage Vertex AI Workbench notebook instances - start, stop, upgrade, diagnose - across Google Cloud regions.
Use for: I need to provision a new GPU-backed notebook instance, Stop all idle notebook instances in a region, Upgrade a notebook instance to the latest framework image, Diagnose a notebook instance that fails to start
Not supported: Does not run notebook code, train models, or store data - use for managed notebook instance lifecycle operations only.
The Notebooks API manages Vertex AI Workbench managed notebook instances on Google Cloud. It provisions, starts, stops, upgrades, resets, and diagnoses Jupyter-based development environments backed by Compute Engine VMs with pre-installed ML frameworks. Use it to spin up GPU/TPU-equipped notebook VMs for data scientists, restore from backup, rollback to prior states, and pull diagnostic bundles when an instance misbehaves. The spec exposes 23 endpoints across regional locations.
Install Jentic One Beta
Connect the Notebooks API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Notebooks API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fgoogleapis.com%2Fnotebooks" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fgoogleapis.com%2Fnotebooks" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Notebooks API.
Provision notebook instances with specific machine types, accelerators, and disk sizes
Start, stop, and reset running notebook VMs to control compute spend
Upgrade instance system images and rollback to prior versions when upgrades fail
Restore notebook instance state from backups taken on a defined schedule
Diagnose unhealthy instances and download diagnostic bundles for support cases
Audit instance configuration via instances:getConfig before applying changes
Use Cases
Patterns agents use Notebooks API for, with concrete tasks.
★ Self-service data science environments
Provision Vertex AI Workbench notebook instances for individual data scientists with consistent ML framework images, machine types, and accelerator attachments. The API gives platform teams a programmatic surface to enforce standards - VPC, service account, encryption key - while giving users on-demand compute. Pairs naturally with policy-as-code so each new instance is created from a vetted template.
Create a notebook instance named ds-anna-gpu in us-central1-a with machine type n1-standard-8, one Tesla T4 accelerator, and a 200 GB boot disk.
Cost control through automated start/stop
Schedule notebook instance start and stop operations to reduce compute bills outside working hours. The API exposes :start, :stop, and :reset operations that fit cleanly inside Cloud Scheduler or a workflow runner. Combined with diagnostic downloads, this is enough to operate a hands-off notebook fleet for a data team.
List all notebook instances in europe-west1, filter to those whose state is ACTIVE, and POST :stop on each instance whose name ends with -dev.
Notebook image upgrades and rollback
Upgrade notebook instances to newer framework images for security patches and library updates, with the safety net of :rollback when an upgrade breaks user workflows. The API records upgrade history so an agent can detect a recent upgrade and revert it without manual intervention. Useful for platform teams that maintain a managed notebook offering.
Trigger upgrade on notebook instance ds-anna-gpu, poll the long-running operation, and execute :rollback if a follow-up health check returns FAILED.
AI agent operations on notebook fleets via Jentic
Operations agents can use Jentic to diagnose and remediate failing notebook instances - issuing intents like diagnose stuck notebook or restore from backup - and Jentic returns the matching Notebooks API operation. Credentials stay in your Jentic One instance, so agents act under scoped service-account tokens with full audit trail.
Use Jentic to find the diagnose operation for a notebook instance, load its schema, and execute it on instance ds-anna-gpu, then download the resulting diagnostic bundle.
Key Endpoints
23 endpoints — the notebooks api manages vertex ai workbench managed notebook instances on google cloud.
METHOD
PATH
DESCRIPTION
POST
/v2/{+parent}/instances
Create a notebook instance
POST
/v2/{+name}:start
Start a stopped instance
POST
/v2/{+name}:stop
Stop a running instance
POST
/v2/{+name}:upgradeSystem
Upgrade the system image
POST
/v2/{+name}:rollback
Rollback to a prior revision
POST
/v2/{+name}:diagnose
Generate a diagnostic bundle
POST
/v2/{+name}:restore
Restore an instance from backup
POST
/v2/{+parent}/instances
Create a notebook instance
POST
/v2/{+name}:start
Start a stopped instance
POST
/v2/{+name}:stop
Stop a running instance
POST
/v2/{+name}:upgradeSystem
Upgrade the system image
POST
/v2/{+name}:rollback
Rollback to a prior revision
POST
/v2/{+name}:diagnose
Generate a diagnostic bundle
POST
/v2/{+name}:restore
Restore an instance from backup
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
N
Notebooks API
- Foundational (D-)40/100
55
Foundational Compliance56
Developer Experience & Jentic Compatibility18
AI-Readiness & Agent Experience94
Agent Usability63
Security61
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
55
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: CSignals: 4
71%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
50%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
56
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: CSignals: 4
0%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
25%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
18
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: FSignals: 4
73%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
0%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
0%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
63
Security
Trust, risk posture, and security compliance.
Grade: B-Signals: 1
62%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
61
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: B-Signals: 1
61%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Notebooks API by hand means setting up Google OAuth 2.0 from a service account, minting scoped tokens, and polling the long-running instance lifecycle operations against notebooks.googleapis.com yourself. Through Jentic you install once, import the Notebooks API from the API Directory, store the OAuth credential once, and your agent calls it.
Permission scoping
The Notebooks API puts the instance in the URL path (/v1/{+name}:start, /v1/{+name}:stop), so a rule can pin your agent to one notebook instance: it can start, stop, and diagnose that instance and nothing else. You choose the operations it may call, so disruptive ones like rollback or restore are not included unless you add them.
Credential isolation
Your Google OAuth credential for the Notebooks API is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'provision a GPU notebook' or 'diagnose a stuck instance', and Jentic returns the matching Notebooks API operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Notebooks API through Jentic.
What authentication does the Notebooks API use?
The API uses Google OAuth 2.0 with the cloud-platform scope. Jentic mints scoped, short-lived tokens from a service account stored in its vault so agents never see raw credentials.
Can I attach a GPU to a notebook instance through this API?
Yes. Set acceleratorConfig in the instance body when calling POST /v2/{+parent}/instances; supported accelerator types follow Compute Engine's GPU SKU list for the chosen zone.
What are the rate limits for the Notebooks API?
Google Cloud enforces per-project quotas on instance create/update operations. Treat lifecycle changes as long-running - the API returns an operation, not a synchronous result, so back-off polling beats retry storms.
How do I diagnose a stuck notebook through Jentic?
Search Jentic for diagnose notebook instance, load the schema for POST /v2/{+name}:diagnose, and execute it with the diagnostic config. The returned operation eventually contains a GCS path to the diagnostic bundle.
Does this API run notebook code itself?
No - the API is a control plane for instance lifecycle. The actual Jupyter kernel runs inside the Compute Engine VM that backs the notebook instance and is reached via JupyterLab over a tunnelled HTTPS connection.
How do I rollback after a failed upgrade?
POST to /v2/{+name}:rollback with the targetSnapshot or revisionId from the prior version, then poll the returned operation until done is true.
Can I limit what my agent is allowed to do with the Notebooks API?
Yes. Because you self-host Jentic One, your own rules decide which Notebooks API operations and credentials the agent may use. Since the instance name sits in the URL path (for example /v2/{+name}:start and /v2/{+name}:stop), you can pin an agent to a single notebook instance and grant it only start, stop, and diagnose calls. Disruptive operations such as :rollback and :restore stay unavailable unless you explicitly add them to the agent's allowed set.
GET STARTED