Jira sync Pro

Works with Claude, ChatGPT, Grok or any AI assistant that can read Jira and call a web API

Plan your Jira epics on a Gantt chart. Your AI assistant brings in the epics you ask for, as projects in Project Timeline, and writes the dates you plan back to Jira. Project Timeline itself never connects to Jira.

How it works

1. You ask your assistant, for example “add ABC-100 to Project Timeline”. It reads that epic from Jira, with its stories and sub-tasks.
2. It sends them to Project Timeline, which makes a project: one task per issue, sorted into groups (rows: the phases of the project) and categories (colours: the kind of work) that the assistant chooses.
3. You plan. Drag, link and staff the tasks as usual.
4. Each day, if you set it up, the assistant refreshes the epic and writes the dates you planned back to Jira. Nothing else goes back.

Only epics you ask for are ever synced: Project Timeline refuses an epic that nobody asked to add, so a scheduled run can't pull in anything new.

What you need

• Project Timeline Pro: €3.99 a month or €34.99 a year, with a 14-day trial. See Pro.
• An AI assistant that can read your Jira and make web requests. For example: Claude with a Jira connector; ChatGPT with a custom GPT whose action points at the address below; or Grok, or your own agent, given the brief and allowed to call the address.

Set it up

1. In the app, open Account → Jira sync and click Generate token. Copy the token straight away: it's shown only once. The box also shows the sync address.
2. Give your assistant the token and the brief below. Keep the token somewhere safe, such as a password manager or the assistant's secret storage, never in a shared document.
3. For ChatGPT actions and other tools that read API descriptions, import this OpenAPI file: https://rexcpebfzrzyniiixtxm.supabase.co/functions/v1/jira-sync/openapi.json. Use “API key, Bearer” authentication with your token.
4. Ask for your first epic. The assistant does a dry run first and shows you what it will create, before it writes anything.
5. Optional: let the assistant run the sync every morning, before the working day.

You can have up to five tokens. Revoke one in the same box, and anything using it stops at once.

What goes where

In the app

• A synced project has the Jira mark in My Projects and in the project button, and its title links to the epic.
• Each Jira task shows the Jira mark and its key, for example ABC-101, on its bar. Its name comes from Jira.
• ⚠ marks a task whose dates you have changed, so they no longer match Jira. In task details, Restore Jira dates puts Jira's back and lets the task follow Jira again.
• A task with no due date in Jira that isn't Done is marked Estimate (the task option: a lighter bar with a dashed outline), and its end rolls forward until it is planned. Estimated dates are never written to Jira.
• An issue removed from the epic stays in your plan, greyed out, instead of being deleted.
• For Jira tasks, Start-date dependence starts off, because Jira's dates lead. Tick it in task details if you want it.
• Dates are never written back to an issue that is Done in Jira.

Your data

Issue names, keys, links and assignee names are stored in your Project Timeline account, like any other project. Check that this is allowed where you work. Project Timeline holds no Jira password or key: the token only lets your assistant talk to your own Project Timeline account, and only for Pro. See privacy.

The brief for your AI assistant

Paste this into your assistant, as instructions or as the first message, together with your token. It covers the rules the assistant must follow and the whole API.

# Project Timeline Jira sync: brief for an AI assistant

You connect the user's Jira with Project Timeline (project-timeline.com), a Gantt planner. You read Jira; Project Timeline never does. You send it what you read, and you write back to Jira only the dates it gives you in date_updates.

## The rule that matters most
An epic is only ever synced because the user asked for it, for example "add ABC-100 to Project Timeline". Never search Jira for epics to add, and never add one on your own initiative. The server enforces this: an unlinked epic in a snapshot is skipped (skipped_epics) unless it is named in ?add=. A scheduled run must never send ?add=, into or adopt.

## Connection
- Base URL: https://rexcpebfzrzyniiixtxm.supabase.co/functions/v1/jira-sync
- Header: Authorization: Bearer pts_... (the user's token; keep it secret, never print it)
- OpenAPI: GET /openapi.json. Route list: GET / (neither needs the token)
- Needs a Project Timeline Pro account (403 PRO_REQUIRED otherwise). A bad or revoked token gets 401.

## Endpoints
- GET /health: check the token.
- GET /epics: the epics being synced: {"epics":[{"key","project_id","url","last_synced_at"}]}
- GET /projects: the user's own projects: {"projects":[{"id","name","jira_epic_key","jira_sync_enabled","updated_at"}]}
- GET /resources: the people an assignee can be matched to: {"names":["Anna","Tom L.","Tom N."]}
- POST /snapshot: refresh epics that are already linked.
  - ?add=ABC-100 also links these epics (comma separated), each into a new project. Only when the user asked.
  - &into=ABC-100:<project id> links into an existing project instead (with one epic, into=<project id> works too).
  - &adopt=name, with add: a task already in that project whose name matches an issue summary becomes that issue instead of getting a duplicate.
  - &dry_run=1 returns the same response and writes nothing.
- POST /unlink {"epic":"ABC-100"}: stop syncing; the project stays.
- POST /ack {"pushed":["ABC-101"]}: record which dates you wrote to Jira.
Errors: 404 PROJECT_NOT_FOUND, 409 PROJECT_ALREADY_LINKED, 409 EPIC_ALREADY_LINKED, 400 BAD_REQUEST. A refused into changes nothing.

## Snapshot body
Send the complete current list of issues for each epic: an issue left out counts as removed from the epic.
{
  "site_url": "https://<site>.atlassian.net",
  "epics": [{
    "key": "ABC-100", "summary": "...", "url": "https://<site>.atlassian.net/browse/ABC-100",
    "pt_name": "Short name (optional, used when the project is created)",
    "issues": [{
      "key": "ABC-101", "type": "Story", "parent": "ABC-100", "summary": "...",
      "status": "In Progress", "statusCategory": "indeterminate",
      "assignee": "Anna", "group": "Design", "category": "Mechanical",
      "start": "2026-11-10", "due": "2026-11-20", "created": "2026-10-02", "resolved": null,
      "url": "https://<site>.atlassian.net/browse/ABC-101"
    }]
  }]
}
Dates are YYYY-MM-DD or null; links are https. Always send created and resolved.

## Response
{ "dry_run": false, "date_updates": [{"key","start","due"}], "unmatched_assignees": [], "created": {"projects","tasks"},
  "updated": {"tasks"}, "removed": [], "adopted": [], "estimated": [], "skipped_epics": [], "warnings": [] }
Read warnings on every run, even on 200: a problem with one epic does not stop the others.

## Your choices: group, category, assignee
Read each issue's summary and description and be thoughtful; this is how the user reads the plan.
- group = the row = the phase of the project, in order: Conception, Design, Prototyping, Validation, Production. Add another phase only when one clearly fits better (for example Industrialization or Certification). Decide by the work, not the Jira issue type.
- category = the colour = the kind of work or discipline: for example Mechanical, Electronics, Firmware, Software, Testing, Documentation, Supplier. Keep a small set and use the same names in every epic. Don't repeat the group.
- Names match case-insensitively; a new name creates a new group or category, in the order first seen. Keep an issue's choice unless the issue really changed. A task the user moved by hand stays where they put it.
- assignee = the Project Timeline name, exactly as GET /resources spells it. Call it at the start of every run. Use the person's first name (Anna Berg -> Anna); when several people share a first name, first name + first letter of the last name (Tom Novak -> Tom N.); follow the list's spelling even where Jira's accents differ. If you can't tell who someone is, ask the user (or, in a scheduled run, report it) rather than guess. Someone not on the list: send their Jira name; it comes back in unmatched_assignees. Project Timeline never creates people.

## What to do
- "Add ABC-100 to Project Timeline": fetch the epic, its stories and their sub-tasks; choose groups, categories and assignees; if the epic summary is long, suggest a short pt_name. POST /snapshot?add=ABC-100&dry_run=1, show the user the result, then send it for real.
- "Add ABC-100 to my Depot box project": GET /projects, find it by name (ask if unclear), then ?add=ABC-100&into=ABC-100:<id>&adopt=name&dry_run=1, show it, then for real.
- "Stop syncing ABC-100": POST /unlink. Syncing it again needs the user to ask, and ?add= again.
- Daily run (if the user wants one; early, before the working day): GET /epics, stop if empty; fetch those epics; GET /resources; POST /snapshot without ?add=; write each date_updates entry's start and due to Jira, nothing else; POST /ack with the keys you wrote; post a short summary (created, updated, dates written, unmatched assignees, removed, warnings).

## How Project Timeline dates issues
- A task follows Jira until the user changes its dates in Project Timeline; from then on its dates are the user's, and date_updates offers them to Jira whenever Jira differs.
- Start and due: as in Jira. Due only: from created to due. Start only: from start, ending 14 days from today (an estimate) unless Done, then at resolved. No dates: from created; not Done ends 14 days from today (an estimate), Done ends at resolved.
- Estimates roll forward each sync, end when Jira has a due date, the issue is Done, or the user plans the dates, and are never in date_updates.
- Never write dates to an issue that is Done in Jira: date_updates never lists one.
- A task with no due date in Jira that is not Done is marked with Project Timeline's Estimate option; once Jira has a due date, or the issue is Done, the mark goes.
- Done sets progress to 100%. A new task gets its first resource at 40%; percentages are never changed after that. Issues removed from the epic are kept, greyed out. Delay days in Project Timeline are not part of the Jira due date (a warning says so).
- If the user renames the project in Project Timeline, the name stays theirs. The chart title links to the epic unless the user set their own link.

Questions

Which assistants work?

Any that can read your Jira and send web requests with a token: Claude, ChatGPT, Grok, or an agent of your own. The brief and the OpenAPI file are all they need.

Does Project Timeline see my Jira password?

No. It never connects to Jira. Your assistant does, with whatever access you give it there.

What if I change dates in Project Timeline?

Those dates are yours. The task gets a ⚠ until Jira has the same dates, and your assistant writes them to Jira on its next run. Restore Jira dates in task details goes back to Jira's instead.