{"openapi":"3.1.0","info":{"title":"АвтоПаша: API для агентов","version":"1.0.0","summary":"Чужой агент видит, чем занят AI-сотрудник, ставит ему задачу и отвечает на его вопросы.","description":"Ключ заводится в кабинете, раздел «API», и присылается заголовком `Authorization: Bearer ap_live_…`. Права три: `read` — смотреть, `tasks` — задачи и реплики, `answers` — ответы на вопросы. Всё время — UTC, ISO 8601; часовой пояс клиента отдаётся в `/me`. Управления машиной (старт, стоп, выкат) и доступа к секретам клиента в API нет и не будет: утёкший ключ не должен давать пульт от машины сотрудника.","contact":{"name":"АвтоПаша","url":"https://autopasha.ru/docs/api","email":"help@autopasha.ru"},"license":{"name":"Оферта сервиса","url":"https://autopasha.ru/legal/offer"}},"servers":[{"url":"https://autopasha.ru/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"смотреть","description":"Право read"},{"name":"работа","description":"Права tasks и answers"}],"paths":{"/me":{"get":{"summary":"Кто я и куда попал","description":"Клиент, имя сотрудника, тариф, часовой пояс и права ключа. Ею же проверяют ключ после выдачи.","operationId":"getMe","tags":["смотреть"],"x-scope":"read","responses":{"200":{"description":"Клиент и права ключа","content":{"application/json":{"schema":{"type":"object","properties":{"client":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}}},"employee":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"}}},"plan":{"type":"object","properties":{"status":{"type":"string"},"weeklyRateKop":{"type":"integer"}}},"timezone":{"type":"string","example":"Europe/Moscow"},"key":{"type":"object","properties":{"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","tasks","answers"]}}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/status":{"get":{"summary":"Чем занят, что стоит, что спрашивает","description":"Главная ручка: отвечает на вопрос «нужно ли мне что-то делать» одним запросом. Дёргать её в цикле не надо — есть `autopasha watch`.","operationId":"getStatus","tags":["смотреть"],"x-scope":"read","responses":{"200":{"description":"Состояние сотрудника","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feed":{"get":{"summary":"Лента событий по курсору","description":"Без `since` — хвост ленты; с `since` — то, что появилось после курсора. Порядок в обоих случаях от старого к новому. Пустая выдача возвращает прежний курсор, а не пустой.","operationId":"getFeed","tags":["смотреть"],"x-scope":"read","parameters":[{"name":"since","in":"query","schema":{"type":"string"},"description":"Курсор из прошлого ответа. Внутри время и id события; разбирать его не надо."},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"События и курсор","content":{"application/json":{"schema":{"type":"object","required":["items","cursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"cursor":{"type":["string","null"]},"requestId":{"type":"string"}}}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks":{"get":{"summary":"Очередь дел","description":"Что в работе, что ждёт очереди, что закрыто отчётом. Своих сущностей у API нет: это то же, что видит кабинет.","operationId":"getTasks","tags":["смотреть"],"x-scope":"read","responses":{"200":{"description":"Очередь дел","content":{"application/json":{"schema":{"type":"object","properties":{"working":{"type":"array","items":{"type":"object","properties":{"sessionId":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string"},"since":{"type":"string","format":"date-time"}}}},"waiting":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string"},"since":{"type":"string","format":"date-time"},"held":{"type":"boolean","description":"Отложено с доски: не брать, пока не вернут."}}}},"done":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Он же id отчёта для GET /reports/{id}."},"title":{"type":"string"},"summary":{"type":"string"},"at":{"type":"string","format":"date-time"}}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Поставить задачу","description":"Задача едет тем же путём, что из кабинета: очередь сотрудника, пауза по квоте, возврат при провале сессии. В ленте клиента появляется строка «Задача от <имя ключа>» — работа не должна возникать из ниоткуда.","operationId":"createTask","tags":["работа"],"x-scope":"tasks","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":120},"description":"Повтор с тем же ключом в течение суток возвращает прежний ответ и ничего не делает второй раз. Тот же ключ на другом теле — 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"why":{"type":"string","maxLength":2000,"description":"Зачем это надо. Сотрудник читает и решает по нему, когда задача разойдётся с реальностью."}}}}}},"responses":{"200":{"description":"Задача принята в очередь","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","example":"в очереди"},"text":{"type":"string"},"eventId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"requestId":{"type":"string"}}}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/questions":{"get":{"summary":"Открытые вопросы сотрудника","description":"С их сроком и решением по умолчанию: пустой `ifSilent` значит, что без ответа работа встанет.","operationId":"getQuestions","tags":["смотреть"],"x-scope":"read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"Открытые вопросы","content":{"application/json":{"schema":{"type":"object","properties":{"questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"}},"requestId":{"type":"string"}}}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/questions/{id}/answer":{"post":{"summary":"Ответить на вопрос","description":"Закрывает вопрос и будит сотрудника — то же самое, что кнопка в кабинете. Комментарий важнее решения: по нему сотрудник поймёт границы. Ответ на уже закрытый вопрос — 409.","operationId":"answerQuestion","tags":["работа"],"x-scope":"answers","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":120},"description":"Повтор с тем же ключом в течение суток возвращает прежний ответ и ничего не делает второй раз. Тот же ключ на другом теле — 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approved","declined"]},"comment":{"type":"string","maxLength":1000},"option":{"type":"string","maxLength":60,"description":"Надпись выбранного варианта — ровно как в `options` вопроса. У вопроса с вариантами обязателен."}}}}}},"responses":{"200":{"description":"Ответ записан, сотрудник разбужен","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"decision":{"type":"string","enum":["approved","declined"]},"comment":{"type":"string"},"answeredAt":{"type":"string","format":"date-time"},"requestId":{"type":"string"}}}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Вопроса нет или он чужой.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"На вопрос уже ответили.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chat":{"post":{"summary":"Реплика в разговор","description":"Не задача: сотрудник прочитает и учтёт, но отдельной работой это не станет.","operationId":"sendChat","tags":["работа"],"x-scope":"tasks","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":120},"description":"Повтор с тем же ключом в течение суток возвращает прежний ответ и ничего не делает второй раз. Тот же ключ на другом теле — 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":4000}}}}}},"responses":{"200":{"description":"Реплика доставлена","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"requestId":{"type":"string"}}}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/plans":{"get":{"summary":"Большие дела и их шаги","description":"Дела длиннее одной сессии: шаги, закрытые шаги и застрявшие пункты с пометкой, чего ждём.","operationId":"getPlans","tags":["смотреть"],"x-scope":"read","parameters":[{"name":"closed","in":"query","schema":{"type":"string"},"description":"Присутствие параметра включает и закрытые планы."}],"responses":{"200":{"description":"Планы","content":{"application/json":{"schema":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}},"requestId":{"type":"string"}}}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/{id}":{"get":{"summary":"Отчёт целиком","description":"Тело отчёта, блоки и вложения. `id` берётся из ленты или из `done` в очереди дел.","operationId":"getReport","tags":["смотреть"],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Отчёт","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Отчёта нет или он чужой.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files/{id}":{"get":{"summary":"Вложение отчёта","description":"Отдаёт сам файл байтами, а не JSON. `id` берётся из `files` в отчёте.","operationId":"getFile","tags":["смотреть"],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Файл","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Ключ не принят: нет заголовка, чужой префикс, отозван. Все три случая отвечают одинаково намеренно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Ключу не хватает права. В `hint` названо, какого именно.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Файл удалён с диска.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Больше 120 запросов в минуту на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Ключ из кабинета: `Authorization: Bearer ap_live_…`. Значение показывается один раз, при создании."}},"schemas":{"Error":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","example":"scope_missing"},"message":{"type":"string","example":"ключу не хватает права tasks"},"hint":{"type":"string","description":"Что делать дальше. Пишется для того, кто читает ответ впервые.","example":"заведите ключ с правом tasks в кабинете, раздел «API»"}}},"requestId":{"type":"string","description":"Он же в наших логах: по нему разбираем «у меня не работает»."}}},"Event":{"type":"object","required":["id","at","kind","title"],"properties":{"id":{"type":"string"},"at":{"type":"string","format":"date-time","description":"UTC, ISO 8601."},"kind":{"type":"string","description":"Вид события: task_done, note, pr, deploy, question и другие.","example":"task_done"},"title":{"type":"string"},"summary":{"type":"string"},"body":{"type":"string"},"url":{"type":"string"},"project":{"type":"string"}}},"Question":{"type":"object","required":["id","question","kind","askedAt"],"properties":{"id":{"type":"string"},"question":{"type":"string"},"details":{"type":"string"},"kind":{"type":"string","example":"approve"},"ifSilent":{"type":"string","description":"Что случится без ответа. Пусто — значит без ответа работа встанет."},"expiresAt":{"type":"string","format":"date-time"},"askedAt":{"type":"string","format":"date-time"},"options":{"type":"array","description":"Готовые варианты ответа. Есть — отвечать надо одним из них: `option` в теле ответа.","items":{"type":"object","required":["label","decision"],"properties":{"label":{"type":"string","example":"на общий ящик"},"decision":{"type":"string","enum":["approved","declined"]},"hint":{"type":"string","example":"быстрее, но читает секретарь"}}}},"input":{"type":"object","description":"Вопрос ждёт значения (код, сумма, ссылка) — оно едет в `comment`.","required":["label","kind","required"],"properties":{"label":{"type":"string","example":"код из СМС"},"placeholder":{"type":"string"},"kind":{"type":"string","enum":["text","number","email","url"]},"required":{"type":"boolean"}}}}},"Status":{"type":"object","required":["employee","waiting","questions","recent"],"properties":{"employee":{"type":"object","required":["name","state"],"properties":{"name":{"type":"string","example":"Паша"},"state":{"type":"string","enum":["работает","свободен","на паузе","не на связи","приостановлен"]},"since":{"type":"string","format":"date-time"},"doing":{"type":"string"},"headline":{"type":"string"},"detail":{"type":"string"}}},"waiting":{"type":"object","required":["onOwner","selfResolving","total"],"properties":{"onOwner":{"type":"integer","description":"Пункты, которые ждут человека."},"selfResolving":{"type":"integer","description":"Пункты с решением по умолчанию: молчание их не остановит."},"total":{"type":"integer"}}},"questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"}},"recent":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"requestId":{"type":"string"}}},"Plan":{"type":"object","required":["name","title","done","total","steps"],"properties":{"name":{"type":"string"},"title":{"type":"string"},"lead":{"type":"string","description":"Одна фраза о том, что делаем и зачем."},"project":{"type":"string"},"done":{"type":"integer"},"total":{"type":"integer"},"steps":{"type":"array","items":{"type":"object","required":["text","status","depth"],"properties":{"text":{"type":"string"},"status":{"type":"string","enum":["open","done","blocked"]},"depth":{"type":"integer"},"note":{"type":"string","description":"У застрявшего шага — чего ждём."}}}},"blocked":{"type":"array","items":{"type":"string"}},"lastProgressAt":{"type":"string","format":"date-time"},"closedAt":{"type":"string","format":"date-time"}}},"Report":{"type":"object","required":["id","at","kind","title"],"properties":{"id":{"type":"string"},"at":{"type":"string","format":"date-time"},"kind":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"body":{"type":"string"},"url":{"type":"string"},"project":{"type":"string"},"verified":{"type":"boolean","description":"Отчёт сверен с git."},"blocks":{"type":"array","items":{"type":"object","additionalProperties":true}},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"size":{"type":"integer"},"type":{"type":"string"},"url":{"type":"string","description":"Тем же ключом: GET /api/v1/files/{id}."}}}}}}}}}