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.googleapis.com/v1alpha/sessions/SESSION_ID:approvePlan"

Delete Session

Deletes a session.

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

---

Activities

List Activities

Lists activities for a session.

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

Query Parameters:

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

Response:

{
  "activities": [
    {
      "name": "sessions/123/activities/456",
      "createTime": "2026-01-15T10:31:00Z",
      "planGenerated": {
        "plan": "1. Analyze existing code\n2. Create test files\n3. Write tests..."
      }
    },
    {
      "name": "sessions/123/activities/457",
      "createTime": "2026-01-15T10:32:00Z",
      "progressUpdate": {
        "title": "Writing tests",
        "details": "Creating test file for auth module..."
      }
    }
  ],
  "nextPageToken": "..."
}

Activities may include artifacts with code changes:

{
  "artifacts": [
    {
      "changeSet": {
        "gitPatch": {
          "unidiffPatch": "diff --git a/...",
          "baseCommitId": "abc123",
          "suggestedCommitMessage": "Add unit tests for login"
        }
      }
    }
  ]
}

Get Activity

Retrieves a single activity by ID.

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

Script Reference

jules_api.sh

The scripts/jules_api.sh script provides a convenient wrapper for common API operations.

Usage:

# List sources
./scripts/jules_api.sh sources

# List sessions
./scripts/jules_api.sh sessions [--page-size N]

# List activities for a session
./scripts/jules_api.sh activities --session <id> [--page-size N]

# Send message to session
./scripts/jules_api.sh send-message --session <id> --prompt "..."

# Approve plan
./scripts/jules_api.sh approve-plan --session <id>

# Create new session
./scripts/jules_api.sh new-session \
  --source "sources/github/owner/repo" \
  --title "..." \
  --prompt "..." \
  [--branch main] \
  [--auto-pr] \
  [--no-plan-approval]

Flags:

Flag	Description
--source	Source name (format: sources/github/owner/repo)
--title	Session title
--prompt	Task description or message content
--session	Session ID
--branch	Starting branch (default: main)
--auto-pr	Enable automatic PR creation
--require-plan-approval	Require explicit plan approval (default)
--no-plan-approval	Skip plan approval (use for low-risk tasks only)
--page-size	Number of results to return

jules.js

The scripts/jules.js script wraps the Jules CLI for programmatic use.

Usage:

node scripts/jules.js version
node scripts/jules.js list-repos
node scripts/jules.js list-sessions
node scripts/jules.js new --repo owner/repo --task "Your task"
node scripts/jules.js pull --session SESSION_ID

Common Error Patterns

"Source not found" or "Repository not found"

Cause: Repository not connected or incorrect source name format.

Solution:

1. Run ./scripts/jules_api.sh sources to list available sources
2. Ensure you've installed the Jules GitHub app for this repo
3. Use the exact source name from the list (e.g., sources/github/octocat/Hello-World)

"Missing JULES_API_KEY"

Cause: API key not set in environment.

Solution:

export JULES_API_KEY="your-api-key"

Authentication Errors

Cause: Invalid or expired API key.

Solution:

1. Generate a new API key at https://jules.google.com/settings#api
2. Update the JULES_API_KEY environment variable
3. Note: You can have at most 3 API keys at a time

Session Stuck in AWAITING_PLAN_APPROVAL

Cause: Session was created with requirePlanApproval: true.

Solution:

./scripts/jules_api.sh approve-plan --session SESSION_ID

Task Fails with Vague Error

Cause: Vague prompts may produce unexpected results.

Solution:

• Write clear, specific prompts
• Break large tasks into smaller, focused tasks
• Avoid prompts that require long-running commands (dev servers, watch scripts)

Large Files Skipped

Cause: Files exceeding 768,000 tokens may be skipped.

Solution:

• Break down operations on very large files
• Consider splitting large files before processing

Best Practices

Writing Effective Prompts

1. Be specific: Instead of "fix the bug", say "fix the null pointer exception in auth.js:45 when email is undefined"
2. Provide context: Mention relevant files, functions, or error messages
3. Keep tasks focused: One logical task per session

Monitoring Sessions

1. Poll session state to track progress
2. Check activities for detailed progress updates
3. Handle AWAITING_USER_FEEDBACK state by sending clarifying messages

Security

1. Never include secrets or credentials in prompts
2. Review generated PRs before merging
3. Use requirePlanApproval: true (recommended for all repos, especially production)
4. Only install the Jules GitHub app on repositories you intend to use with Jules — limit access scope
5. Treat JULES_API_KEY as a secret: store it securely, rotate it regularly, and never paste it into untrusted places

Performance

1. Use automationMode: AUTO_CREATE_PR for streamlined workflows
2. Only skip plan approval (requirePlanApproval: false) for routine, low-risk tasks in non-critical repos
3. Break complex tasks into smaller sessions

Extracting Results

When a session completes, retrieve the PR URL from outputs:

# Get session details
curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID" \
  | jq '.outputs[].pullRequest.url'

Known Limitations

• Alpha API: Specifications may change; API keys and definitions are experimental
• No long-running commands: Jules cannot run npm run dev or similar watch scripts
• Context size: Files > 768,000 tokens may be skipped
• Prompt sensitivity: Vague prompts may produce unexpected results

References

• Jules API Documentation
• Sessions Reference
• Activities Reference
• Sources Reference
• Types Reference
• Google Developers - Jules API
• Jules Settings (API Keys)