Jules API

Create and manage Google Jules AI coding sessions to automate tasks like code writing, bug fixing, testing, and PR creation on GitHub repos using the Jules API.

Security Scan

The skill generally matches its stated purpose (calling the Jules REST API with your API key), but there are inconsistencies in the packaged helper script vs. the declared requirements and a few runtime behaviors you should be aware of before installing.

Purpose & Capability

Name/description, declared env var (JULES_API_KEY), and curl usage align with a Jules REST API client. However, the included scripts/jules.sh relies on jq for building and parsing JSON (unconditionally in places) while the skill metadata only lists curl as a required binary. That mismatch means the skill as packaged may fail at runtime unless jq is present, and the metadata underreports the actual runtime footprint.

Instruction Scope

SKILL.md instructs only against Jules endpoints (sessions, sources, activities) and sending the API key via the x-goog-api-key header. There is no instruction to read unrelated files, other environment variables, or exfiltrate data to third parties. Note: the skill supports automation modes (AUTO_CREATE_PR) that will cause Jules to create PRs on connected GitHub repos — this is expected but impactful behavior.

Install Mechanism

No install spec (instruction-only) which reduces supply-chain risk. However, a helper script is included in the bundle (scripts/jules.sh) that will be executed if the user runs it; it writes/executes nothing on install but will run curl and jq at runtime. No external downloads or archive extraction are present.

Credentials

Only JULES_API_KEY is required and is appropriate for the documented API interactions. Users should be aware that the API key grants Jules access to repositories connected to the Jules account (including ability to create PRs when automationMode is used), so key scope and trust in the Jules integration matter.

Persistence & Privilege

Skill does not request always:true and makes no persistent system changes in its files. It does not modify other skills or system-wide agent settings. Autonomous invocation is allowed (platform default) but is not combined with other high-privilege requests.

What to consider before installing

This skill appears to be a genuine Jules REST API helper, but review these points before installing or running it: - The included script (scripts/jules.sh) uses jq to construct and parse JSON, but the skill metadata only lists curl as required. If you run the script without jq installed it will likely fail (set -euo will cause early exit). Install jq or update the script/metadata before use. - The skill requires your JULES_API_KEY. That key gives Jules access to repositories that are connected to your Jules account and can be used to auto-create pull requests (automationMode AUTO_CREATE_PR). Only use with an API key you trust and consider limiting scope or using an account with minimal privileges. - There are no hidden network endpoints or download steps in the package, but the helper script will perform network calls to jules.googleapis.com — inspect the script and test in a controlled environment first. - If you intend to allow autonomous agent actions, be cautious about auto-approve/auto-PR flows; prefer requirePlanApproval unless you trust the automation. If you want to proceed: either install jq on the host or edit the script to avoid jq (or update skill metadata to declare jq in required binaries). If you are unsure about giving Jules account access to important repos, create a low-privilege Jules/GitHub integration for testing and rotate the API key after use.

Jules API Skill

Interact with the Google Jules AI coding agent via its REST API. Jules can autonomously execute coding tasks on your GitHub repositories — writing code, fixing bugs, adding tests, and creating pull requests.

Base URL: https://jules.googleapis.com/v1alpha Auth: Pass your API key via the x-goog-api-key header. Get one at jules.google.com/settings.

---

List Sources (Connected Repositories)

Discover which GitHub repos are connected to your Jules account:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources?pageSize=30"

With pagination:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources?pageSize=10&pageToken=PAGE_TOKEN"

Filter specific sources:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources?filter=name%3Dsources%2Fgithub-owner-repo"

Get a Source

Get details and branches for a specific repo:

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

Example: sources/github-myorg-myrepo — replace with your actual source ID from List Sources.

---

Create a Session (Start a Coding Task)

Create a new Jules session to execute a coding task on a repo:

curl -s -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "TASK_DESCRIPTION",
    "title": "OPTIONAL_TITLE",
    "sourceContext": {
      "source": "sources/github-OWNER-REPO",
      "githubRepoContext": {
        "startingBranch": "main"
      }
    },
    "requirePlanApproval": true
  }' \
  "https://jules.googleapis.com/v1alpha/sessions"

Parameters

Parameter	Required	Description
prompt	Yes	The task description for Jules to execute
title	No	Optional title (auto-generated if omitted)
sourceContext.source	Yes	Source resource name (e.g. sources/github-owner-repo)
sourceContext.githubRepoContext.startingBranch	Yes	Branch to start from (e.g. main, develop)
requirePlanApproval	No	If true, plans need explicit approval before execution
automationMode	No	Set to AUTO_CREATE_PR to auto-create PRs when done

Auto-approve + Auto-PR example

curl -s -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add comprehensive unit tests for the auth module",
    "sourceContext": {
      "source": "sources/github-myorg-myrepo",
      "githubRepoContext": { "startingBranch": "main" }
    },
    "automationMode": "AUTO_CREATE_PR"
  }' \
  "https://jules.googleapis.com/v1alpha/sessions"

---

List Sessions

List all your Jules sessions:

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

Paginate with pageToken:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=10&pageToken=NEXT_PAGE_TOKEN"

Get a Session

Retrieve a single session by ID (includes outputs like PRs if completed):

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

Session States

State	Meaning
QUEUED	Waiting to be processed
PLANNING	Jules is analyzing and creating a plan
AWAITING_PLAN_APPROVAL	Plan ready, waiting for user approval
AWAITING_USER_FEEDBACK	Jules needs additional input
IN_PROGRESS	Jules is actively working
PAUSED	Session is paused
COMPLETED	Task completed successfully
FAILED	Task failed to complete

---

Approve a Plan

When a session is in AWAITING_PLAN_APPROVAL state, approve the plan:

curl -s -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:approvePlan"

Send a Message

Send feedback, answer questions, or give additional instructions to an active session:

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

Use this when session state is AWAITING_USER_FEEDBACK or to provide additional guidance during IN_PROGRESS.

---

List Activities (Monitor Progress)

Get all events/progress for a session:

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

Get activities after a specific timestamp (for polling):

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities?createTime=2026-01-17T00:03:53Z"

Activity Types

Activities will contain exactly one of these event fields:

Event	Description
planGenerated	Jules created a plan (contains plan.steps[])
planApproved	A plan was approved
userMessaged	User sent a message
agentMessaged	Jules sent a message
progressUpdated	Status update during execution
sessionCompleted	Session finished successfully
sessionFailed	Session encountered an error (contains reason)

Artifacts

Activities may include artifacts:

• ChangeSet: Code changes with gitPatch (unified diff, base commit, suggested commit message)
• BashOutput: Command output with command, output, exitCode
• Media: Binary output with mimeType and base64 data

Get a Single Activity

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

---

Delete a Session

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

---

Typical Workflow

1. List sources to find the repo resource name
2. Create a session with a prompt describing the task
3. Poll the session (Get Session) to track state changes
4. List activities to monitor progress and read Jules' messages
5. If requirePlanApproval was set, approve the plan when state is AWAITING_PLAN_APPROVAL
6. If state is AWAITING_USER_FEEDBACK, send a message with your response
7. When COMPLETED, get the session to find the output PR URL

Error Handling

Code	Meaning
200	Success
400	Bad request (invalid parameters)
401	Unauthorized (invalid/missing API key)
403	Forbidden (insufficient permissions)
404	Not found
429	Rate limited
500	Server error

Error responses return:

{
  "error": {
    "code": 400,
    "message": "Invalid session ID format",
    "status": "INVALID_ARGUMENT"
  }
}

Notes

• Get your API key from jules.google.com/settings
• Store it as the JULES_API_KEY environment variable
• Sources (repos) are connected via the Jules web UI at jules.google — the API is read-only for sources
• Session resource names follow the pattern sessions/{sessionId}
• Activity resource names follow sessions/{sessionId}/activities/{activityId}
• All list endpoints support pageSize (1-100) and pageToken for pagination