Agent Control API (1.0.0)

Download OpenAPI specification:

Interface between the frontend and backend of the Agent Control application.

Initiate Google SSO login

Redirects the user to Google for authentication.

Responses

Google SSO callback

Handles the response from Google and logs the user in.

query Parameters

code

required

string

Examples:

code=4/0AfgeXvv-some-token-123 -

Responses

Log out

Destroys the user session.

Responses

Initiate GitHub OAuth

Redirects the user to GitHub for account linking.

Responses

GitHub OAuth callback

Handles the response from GitHub and links the account.

query Parameters

code

required

string

Examples:

code=github_code_123 -

Responses

Dashboard

Displays user projects and linked GitHub accounts.

query Parameters

success	string Examples: success=project_created -
github	string Examples: github=success -
delete_project	integer Examples: delete_project=1 -
csrf_token	string Examples: csrf_token=token_abc_123 -

Responses

Link new repository

Creates a new project by linking a GitHub repository.

Request Body schema: application/x-www-form-urlencoded

github_repo	string
github_account_id	integer
csrf_token	string

Responses

Request samples

Payload

Content type

application/x-www-form-urlencoded

github_repo=google%2Fjules&github_account_id=1&csrf_token=token_abc_123

Project details

Displays tasks and logs for a specific project.

query Parameters

id

required

integer

Examples:

id=1 -

Responses

Response samples

200

Content type

text/html

<html>...google/jules...</html>

Trigger agent

Manually triggers the Jules agent for a specific task.

Request Body schema: application/x-www-form-urlencoded

trigger_agent	string
task_id	integer
csrf_token	string

Responses

Request samples

Payload

Content type

application/x-www-form-urlencoded

trigger_agent=Run%20Agent&task_id=42&csrf_token=token_abc_123

Response samples

200

Content type

text/html

<html>...Agent response...</html>

GitHub Webhook

Receives 'issues' events from GitHub.

header Parameters

X-Hub-Signature-256 required	string Examples: sha256=hash_here -
X-GitHub-Event required	string Value: "issues" Examples: issues -

Request Body schema: application/json

action	string
	object
	object

Responses

Request samples

Payload

Content type

application/json

{"action": "opened",
"issue": {"number": 101,
"title": "Bug: App crashes",
"body": "Steps to reproduce..."
},
"repository": {"full_name": "google/jules"
}
}

Response samples

200

Content type

text/plain

OK

Telegram Webhook

Receives updates from the Telegram Bot API.

header Parameters

X-Telegram-Bot-Api-Secret-Token

required

string

Examples:

secret_token_123 -

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"update_id": 12345,
"message": {"message_id": 1,
"from": {"id": 98765,
"first_name": "John"
},
"chat": {"id": 98765,
"type": "private"
},
"date": 1610000000,
"text": "/start token_abc"
}
}

Response samples

200

Content type

text/plain

OK

Admin dashboard

User management for administrators.

Responses

Response samples

200

Content type

text/html

<html>...User Management...</html>

Obtain JWT token

Issues a JWT access token and a refresh token for the currently session-authenticated user.

Responses

Response samples

200

Content type

application/json

{"access_token": "string",
"refresh_token": "string",
"token_type": "string",
"expires_in": 0
}

Refresh JWT token

Exchanges a valid refresh token for a new access token and refresh token.

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

{"access_token": "string",
"refresh_token": "string",
"token_type": "string",
"expires_in": 0
}

List user projects (JSON)

Returns a list of projects associated with the authenticated user.

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"user_id": 1,
"github_account_id": 1,
"github_repo": "google/jules",
"webhook_secret": "secret_123",
"created_at": "2023-10-27T10:05:00Z",
"github_username": "johndoe_git",
"blockly_config": {"xml": "string",
"js": "string"
},
"roadmap_data": [{"name": "string",
"html_url": "string",
"next_task": "string"
}
],
"roadmap_updated_at": "2023-10-27T10:05:00Z"
}
]

Link new repository

Creates a new project by linking a GitHub repository.

Authorizations:

BearerAuth

Request Body schema: application/json

github_repo required	string
github_account_id required	integer

Responses

Request samples

Payload

Content type

application/json

{"github_repo": "string",
"github_account_id": 0
}

Response samples

200

Content type

application/json

{"status": "string",
"project_id": 0,
"message": "string"
}

Get project details (JSON)

Returns details for a specific project, including roadmap data.

Authorizations:

BearerAuth

query Parameters

id

required

integer

Project ID

Responses

Response samples

200

Content type

application/json

{"id": 1,
"user_id": 1,
"github_account_id": 1,
"github_repo": "google/jules",
"webhook_secret": "secret_123",
"created_at": "2023-10-27T10:05:00Z",
"github_username": "johndoe_git",
"blockly_config": {"xml": "string",
"js": "string"
},
"roadmap_data": [{"name": "string",
"html_url": "string",
"next_task": "string"
}
],
"roadmap_updated_at": "2023-10-27T10:05:00Z"
}

Perform project action

Triggers actions like issue synchronization, creating issues from templates/roadmap, or updating settings.

Authorizations:

BearerAuth

query Parameters

id

required

integer

Project ID

Request Body schema: application/json

action required	string Enum: "sync_issues" "create_from_template" "create_from_roadmap" "update_settings" "update_notifications" "create_github_issue"
title	string Required for 'create_github_issue'
body	string Optional for 'create_github_issue'
labels	Array of strings Optional labels for 'create_github_issue'
template_id	integer Required for 'create_from_template'
	object Parameter values for the template
roadmap_name	string Required for 'create_from_roadmap'
github_repo	string Required for 'update_settings'
github_account_id	integer Required for 'update_settings'
blockly_config	string or null Optional for 'update_settings'
	object Required for 'update_notifications'

Responses

Request samples

Payload

Content type

application/json

{"action": "sync_issues",
"title": "string",
"body": "string",
"labels": ["string"
],
"template_id": 0,
"params": {"property1": "string",
"property2": "string"
},
"roadmap_name": "string",
"github_repo": "string",
"github_account_id": 0,
"blockly_config": "string",
"status_settings": {"property1": true,
"property2": true
}
}

Response samples

200

Content type

application/json

{"status": "string",
"message": "string"
}

Delete project

Deletes a project.

Authorizations:

BearerAuth

query Parameters

id

required

integer

Project ID

Responses

List tasks (JSON)

Returns a list of tasks, optionally filtered by project or status.

Authorizations:

BearerAuth

query Parameters

id	integer Project ID (optional)
filter	string Enum: "all_open" "github_running" "github_passed" "github_failed" "jules_analyzing" "jules_executing" "jules_failed" "open_issues" Filter criteria

Responses

Response samples

200

Content type

application/json

[{"id": 42,
"project_id": 1,
"issue_number": 101,
"title": "Bug: App crashes",
"body": "Steps to reproduce...",
"status": "created",
"agent_response": "The bug is caused by...",
"pr_url": "https://github.com/google/jules/pull/123",
"jules_url": "https://jules.google.com/task/abc-123",
"jules_status": "coding",
"github_state": "open",
"github_repo": "google/jules",
"created_at": "2023-10-27T10:10:00Z",
"last_synced_at": "2023-10-27T10:15:00Z",
"autorepeat_remaining": 5,
"labels": [{"name": "string",
"color": "string"
}
],
"pr_details": {"title": "string",
"body": "string",
"state": "string",
"merged": true,
"base": {"ref": "string"
},
"head": {"ref": "string"
},
"mergeable_state": "string",
"draft": true
},
"jules_messages": [{"user": {"login": "string"
},
"body": "string",
"created_at": "2019-08-24T14:15:22Z",
"html_url": "string"
}
]
}
]

List running autorepeat tasks (JSON)

Returns a list of all active autorepeat tasks for the authenticated user.

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": 42,
"project_id": 1,
"issue_number": 101,
"title": "Bug: App crashes",
"body": "Steps to reproduce...",
"status": "created",
"agent_response": "The bug is caused by...",
"pr_url": "https://github.com/google/jules/pull/123",
"jules_url": "https://jules.google.com/task/abc-123",
"jules_status": "coding",
"github_state": "open",
"github_repo": "google/jules",
"created_at": "2023-10-27T10:10:00Z",
"last_synced_at": "2023-10-27T10:15:00Z",
"autorepeat_remaining": 5,
"labels": [{"name": "string",
"color": "string"
}
],
"pr_details": {"title": "string",
"body": "string",
"state": "string",
"merged": true,
"base": {"ref": "string"
},
"head": {"ref": "string"
},
"mergeable_state": "string",
"draft": true
},
"jules_messages": [{"user": {"login": "string"
},
"body": "string",
"created_at": "2019-08-24T14:15:22Z",
"html_url": "string"
}
]
}
]

Get task details (JSON)

Returns details for a specific task.

Authorizations:

BearerAuth

query Parameters

id

required

integer

Task ID

Responses

Response samples

200

Content type

application/json

{"id": 42,
"project_id": 1,
"issue_number": 101,
"title": "Bug: App crashes",
"body": "Steps to reproduce...",
"status": "created",
"agent_response": "The bug is caused by...",
"pr_url": "https://github.com/google/jules/pull/123",
"jules_url": "https://jules.google.com/task/abc-123",
"jules_status": "coding",
"github_state": "open",
"github_repo": "google/jules",
"created_at": "2023-10-27T10:10:00Z",
"last_synced_at": "2023-10-27T10:15:00Z",
"autorepeat_remaining": 5,
"labels": [{"name": "string",
"color": "string"
}
],
"pr_details": {"title": "string",
"body": "string",
"state": "string",
"merged": true,
"base": {"ref": "string"
},
"head": {"ref": "string"
},
"mergeable_state": "string",
"draft": true
},
"jules_messages": [{"user": {"login": "string"
},
"body": "string",
"created_at": "2019-08-24T14:15:22Z",
"html_url": "string"
}
]
}

Perform task action

Triggers actions like agent execution or PR merging for a task.

Authorizations:

BearerAuth

query Parameters

id

required

integer

Task ID

Request Body schema: application/json

action

required

string

Enum: "trigger_agent" "merge_close" "merge_close_duplicate"

Responses

Request samples

Payload

Content type

application/json

{"action": "trigger_agent"
}

Response samples

200

Content type

application/json

{"status": "string",
"message": "string",
"agent_response": "string"
}

Get task logs (JSON)

Returns logs for a specific task.

Authorizations:

BearerAuth

query Parameters

id

required

integer

Task ID

Responses

Response samples

200

Content type

application/json

[{"id": 500,
"task_id": 42,
"message": "Agent triggered by user John Doe",
"level": "info",
"created_at": "2023-10-27T10:11:00Z"
}
]

List webhook logs (JSON)

Returns a list of webhook logs for the authenticated user or all logs if admin.

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": 1000,
"user_id": 1,
"user_email": "john@example.com",
"endpoint": "github/webhook.php",
"payload": "string",
"headers": "string",
"status_code": 200,
"error_message": "string",
"created_at": "2023-10-27T10:20:00Z"
}
]

List performance logs (JSON)

Returns a list of performance and API logs for the authenticated user or all logs if admin.

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": 2000,
"user_id": 1,
"user_email": "john@example.com",
"type": "api",
"target": "GET /api/projects",
"duration": 0.123,
"context": { },
"status_code": 200,
"error_message": "Not Found",
"created_at": "2023-10-27T10:30:00Z"
}
]

List issue templates (JSON)

Returns a list of issue templates for the authenticated user.

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"name": "Bug Report",
"title_template": "Bug: %1",
"body_template": "Steps to reproduce: %2",
"parameter_config": {"property1": "string",
"property2": "string"
},
"created_at": "2023-10-27T10:00:00Z"
}
]

Create or update issue template

Creates a new issue template or updates an existing one.

Authorizations:

BearerAuth

Request Body schema: application/json

id	integer Template ID (for updates)
name required	string
title_template required	string
body_template	string
	object

Responses

Request samples

Payload

Content type

application/json

{"id": 0,
"name": "string",
"title_template": "string",
"body_template": "string",
"parameter_config": {"property1": "string",
"property2": "string"
}
}

Delete issue template

Deletes an issue template.

Authorizations:

BearerAuth

query Parameters

id

required

integer

Template ID

Responses

Get current user profile (JSON)

Returns the profile and configuration of the currently authenticated user.

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

{"id": 1,
"google_id": "123456789",
"name": "John Doe",
"email": "john@example.com",
"avatar": "https://avatar.url",
"role": "user",
"created_at": "2023-10-27T10:00:00Z",
"telegram_bot_name": "MyAgentBot",
"telegram_bot_token": "string",
"telegram_webhook_secret": "string",
"telegram_chat_id": 123456789,
"jules_api_key": "string",
"has_jules_key": true,
"jules_quota_usage": 150,
"jules_quota_limit": 1000,
"blockly_config": {"xml": "string",
"js": "string"
},
"github_accounts": [{"github_account_id": 0,
"github_username": "string"
}
],
"notification_settings": {"in_app": true,
"browser": true,
"telegram": true
},
"notification_event_settings": {"created": true,
"processing": true,
"ready": true,
"finished": true,
"failed": true,
"analyzing": true,
"planning": true,
"executing": true,
"verifying": true,
"implemented": true,
"checking": true,
"failed_jules": true,
"failed_pr": true
}
}

Update user profile/settings (JSON)

Updates the profile and configuration of the currently authenticated user.

Authorizations:

BearerAuth

Request Body schema: application/json

jules_api_key	string or null
blockly_config	string or null
telegram_bot_name	string or null
telegram_bot_token	string or null
telegram_webhook_secret	string or null
	object
	object

Responses

Request samples

Payload

Content type

application/json

{"jules_api_key": "string",
"blockly_config": "string",
"telegram_bot_name": "string",
"telegram_bot_token": "string",
"telegram_webhook_secret": "string",
"notification_settings": {"in_app": true,
"browser": true,
"telegram": true
},
"notification_event_settings": {"created": true,
"processing": true,
"ready": true,
"finished": true,
"failed": true,
"analyzing": true,
"planning": true,
"executing": true,
"verifying": true,
"implemented": true,
"checking": true,
"failed_jules": true,
"failed_pr": true
}
}

Response samples

200

Content type

application/json

{"id": 1,
"google_id": "123456789",
"name": "John Doe",
"email": "john@example.com",
"avatar": "https://avatar.url",
"role": "user",
"created_at": "2023-10-27T10:00:00Z",
"telegram_bot_name": "MyAgentBot",
"telegram_bot_token": "string",
"telegram_webhook_secret": "string",
"telegram_chat_id": 123456789,
"jules_api_key": "string",
"has_jules_key": true,
"jules_quota_usage": 150,
"jules_quota_limit": 1000,
"blockly_config": {"xml": "string",
"js": "string"
},
"github_accounts": [{"github_account_id": 0,
"github_username": "string"
}
],
"notification_settings": {"in_app": true,
"browser": true,
"telegram": true
},
"notification_event_settings": {"created": true,
"processing": true,
"ready": true,
"finished": true,
"failed": true,
"analyzing": true,
"planning": true,
"executing": true,
"verifying": true,
"implemented": true,
"checking": true,
"failed_jules": true,
"failed_pr": true
}
}

List notifications (JSON)

Returns a list of notifications for the authenticated user.

Authorizations:

BearerAuth

query Parameters

action

string

Enum: "list" "unread_count"

Responses

Response samples

200

Content type

application/json

{"status": "string",
"notifications": [{"notification_id": 0,
"user_id": 0,
"title": "string",
"message": "string",
"title_plain": "string",
"message_plain": "string",
"github_repo": "string",
"is_read": 0,
"created_at": "2019-08-24T14:15:22Z",
"data": {"source_url": "string"
}
}
],
"unread_count": 0,
"settings": { }
}

Perform notification action

Marks notifications as read or clears all.

Authorizations:

BearerAuth

Request Body schema: application/json

action required	string Enum: "mark_read" "mark_all_read" "clear_all" "test_broadcast"
notification_id	integer

Responses

Request samples

Payload

Content type

application/json

{"action": "mark_read",
"notification_id": 0
}

Get global sync status (JSON)

Returns global status counts for GitHub checks and Jules agents.

Authorizations:

BearerAuth

query Parameters

fast	integer Enum: 0 1 If 1, skip external API calls and return cached data.

Responses

Response samples

200

Content type

application/json

{"status": "string",
"quota_usage": 0,
"quota_limit": 0,
"total_tasks": 0,
"open_issues": 0,
"completed_tasks": 0,
"jules_analyzing": 0,
"jules_executing": 0,
"jules_failed": 0,
"github_running": 0,
"github_passed": 0,
"github_failed": 0,
"telegram_connected": true
}

List all users (Admin only)

Returns a list of all users with project counts. Requires admin privileges.

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"google_id": "123456789",
"github_id": "987654321",
"name": "John Doe",
"email": "john@example.com",
"avatar": "https://avatar.url",
"role": "user",
"created_at": "2023-10-27T10:00:00Z",
"project_count": 5
}
]

Get database health check (Admin only)

Returns database connection status, missing patches, table validation, and basic data health. Requires admin privileges.

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

{"connection_status": {"status": "string",
"driver": "string",
"version": "string",
"message": "string"
},
"missing_patches": ["string"
],
"table_status": [{"table": "string",
"exists": true,
"rows": 0,
"error": "string"
}
],
"basic_data_status": [{"name": "string",
"status": "string",
"message": "string"
}
]
}

Get migration status (Admin only)

Returns applied and pending database patches. Requires admin privileges.

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

{"applied": ["string"
],
"pending": ["string"
]
}

Apply database patches (Admin only)

Applies pending database patches. Requires admin privileges.

Authorizations:

BearerAuth

Request Body schema: application/json

patch

string

Default: "all"

Patch name to apply or 'all' to apply all pending.

Responses

Request samples

Payload

Content type

application/json

{"patch": "all"
}

Response samples

200

Content type

application/json

{"status": "string",
"message": "string",
"logs": ["string"
]
}