jules-api

Jules REST API Skill

Quick Start

# 0. Set your API key (required — get one at https://jules.google.com/settings#api)
export JULES_API_KEY="your-api-key-here"

# 1. Verify available sources (pre-flight check)
./scripts/jules_api.sh sources

# 2. Create a session with plan approval and auto PR creation
./scripts/jules_api.sh new-session \
  --source "sources/github/OWNER/REPO" \
  --title "Add unit tests" \
  --prompt "Add comprehensive unit tests for the authentication module" \
  --branch main \
  --require-plan-approval \
  --auto-pr

# 3. Monitor session progress and approve the plan
./scripts/jules_api.sh activities --session SESSION_ID
./scripts/jules_api.sh approve-plan --session SESSION_ID

Note: Use your GitHub username/org, not your local system username (e.g., sources/github/octocat/Hello-World, not sources/github/$USER/Hello-World).

Overview

This skill enables programmatic interaction with the Jules REST API (v1alpha) for delegating coding tasks to Jules, Google's autonomous AI coding agent. It supports:

• Task Assignment: Create new coding sessions with specific prompts
• Session Monitoring: Track session state and activities in real-time
• Plan Management: Approve or review generated plans
• Messaging: Send follow-up messages to active sessions
• Result Integration: Retrieve PR URLs and code changes from completed sessions

Before You Start

1. Get an API Key

Create a Jules API key in the Jules web app:

• Navigate to: https://jules.google.com/settings#api
• You can have at most 3 API keys at a time

Export it on the machine running the agent:

export JULES_API_KEY="your-api-key-here"

2. Connect Your GitHub Repository

Before the API can operate on a GitHub repo, you must:

1. Install the Jules GitHub app via the Jules web UI
2. Grant access to the specific repositories you want Jules to work on

3. Verify Repository Access

# List available sources to verify access and see correct format
./scripts/jules_api.sh sources

You'll see entries like:

{
  "sources": [
    {
      "name": "sources/github/octocat/Hello-World",
      "githubRepo": {
        "owner": "octocat",
        "repo": "Hello-World",
        "defaultBranch": { "displayName": "main" },
        "branches": [
          { "displayName": "main" },
          { "displayName": "develop" }
        ]
      }
    }
  ]
}

Base URL & Authentication

Property	Value
Base URL	https://jules.googleapis.com/v1alpha
Auth Header	x-goog-api-key: $JULES_API_KEY

All requests authenticate with:

-H "x-goog-api-key: $JULES_API_KEY"

Core Concepts

Resources

Resource	Description
Source	A GitHub repository connected to Jules. Format: sources/github/{owner}/{repo}
Session	A unit of work where Jules executes a coding task. Contains state, activities, and outputs
Activity	An individual event within a session (plan generated, message sent, progress update, etc.)

Session States

State	Description
QUEUED	Session is waiting to start
PLANNING	Generating execution plan
AWAITING_PLAN_APPROVAL	Waiting for user to approve plan
AWAITING_USER_FEEDBACK	Needs user input to continue
IN_PROGRESS	Actively executing the task
PAUSED	Temporarily stopped
COMPLETED	Successfully finished
FAILED	Encountered an error

Activity Types

Type	Description
Plan Generated	A plan was generated for the task
Plan Approved	The plan was approved (manually or auto)
User Message	User posted a message to the session
Agent Message	Jules posted a message
Progress Update	Status update on current work
Session Completed	Session finished successfully
Session Failed	Session encountered an error

Workflows

Option 1: Session with Plan Approval and Auto-PR (Recommended)

Create a session that requires plan approval before execution and automatically creates a PR when complete:

./scripts/jules_api.sh new-session \
  --source "sources/github/octocat/Hello-World" \
  --title "Fix login bug" \
  --prompt "Fix the null pointer exception in the login handler when email is empty" \
  --branch main \
  --require-plan-approval \
  --auto-pr

Why this is recommended:

• You review and approve the plan before Jules executes changes
• PR is created automatically on completion
• Balances automation with human oversight

Option 2: Fully Automated Session (No Plan Approval)

For low-risk or routine tasks in non-sensitive repos, you can skip plan approval:

# Create session without plan approval (use only for low-risk tasks)
./scripts/jules_api.sh new-session \
  --source "sources/github/octocat/Hello-World" \
  --title "Fix typo in README" \
  --prompt "Fix the typo in README.md line 5" \
  --branch main \
  --auto-pr

Warning: Without --require-plan-approval, Jules will automatically approve its own plan and execute changes. Only use this for low-risk tasks in non-critical repos.

Option 3: Interactive Session

Send follow-up messages during an active session:

# Create session
./scripts/jules_api.sh new-session \
  --source "sources/github/octocat/Hello-World" \
  --title "Add API endpoints" \
  --prompt "Add REST API endpoints for user management" \
  --branch main

# Send additional instructions
./scripts/jules_api.sh send-message \
  --session SESSION_ID \
  --prompt "Also add input validation for all endpoints"

API Reference

Sources

List Sources

Lists all connected GitHub repositories.

curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources"

Query Parameters:

Parameter	Type	Default	Description
pageSize	integer	30	Number of sources to return (1-100)
pageToken	string	-	Token from previous response for pagination
filter	string	-	AIP-160 filter (e.g., name=sources/source1)

Response:

{
  "sources": [
    {
      "name": "sources/github/octocat/Hello-World",
      "githubRepo": {
        "owner": "octocat",
        "repo": "Hello-World",
        "isPrivate": false,
        "defaultBranch": { "displayName": "main" },
        "branches": [
          { "displayName": "main" },
          { "displayName": "develop" }
        ]
      }
    }
  ],
  "nextPageToken": "..."
}

Get Source

Retrieves a single source by name.

curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources/github/octocat/Hello-World"

Use this to see available branches before creating a session.

---

Sessions

Create Session

Creates a new coding session.

curl -sS "https://jules.googleapis.com/v1alpha/sessions" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -d '{
    "prompt": "Add unit tests for the login module",
    "title": "Add Login Tests",
    "sourceContext": {
      "source": "sources/github/octocat/Hello-World",
      "githubRepoContext": {
        "startingBranch": "main"
      }
    },
    "requirePlanApproval": true,
    "automationMode": "AUTO_CREATE_PR"
  }'

Request Body Fields:

Field	Type	Required	Description
prompt	string	Yes	The task description for Jules
title	string	No	Short title for the session
sourceContext.source	string	Yes	Source name (e.g., sources/github/owner/repo)
sourceContext.githubRepoContext.startingBranch	string	Yes	Branch to start from
requirePlanApproval	boolean	No	If true, pause for plan approval. Recommended: true for production repos
automationMode	string	No	Set to AUTO_CREATE_PR for automatic PR creation

Response:

{
  "name": "sessions/31415926535897932384",
  "id": "31415926535897932384",
  "prompt": "Add unit tests for the login module",
  "title": "Add Login Tests",
  "state": "QUEUED",
  "url": "https://jules.google/session/31415926535897932384",
  "createTime": "2026-01-15T10:30:00Z",
  "updateTime": "2026-01-15T10:30:00Z"
}

List Sessions

Lists your sessions.

curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=20"

Query Parameters:

Parameter	Type	Default	Description
pageSize	integer	30	Number of sessions to return (1-100)
pageToken	string	-	Token from previous response for pagination

Get Session

Retrieves a single session by ID.

curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID"

Response includes outputs on completion:

{
  "name": "sessions/31415926535897932384",
  "id": "31415926535897932384",
  "state": "COMPLETED",
  "outputs": [
    {
      "pullRequest": {
        "url": "https://github.com/octocat/Hello-World/pull/42",
        "title": "Add Login Tests",
        "description": "This PR adds comprehensive unit tests..."
      }
    }
  ]
}

Send Message

Sends a message to an active session.

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:sendMessage" \
  -d '{"prompt": "Also add integration tests"}'

Use this to provide feedback, answer questions, or give additional instructions.

Approve Plan

Approves a pending plan (only needed if requirePlanApproval was true).

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.goo

---

*Content truncated.*