Créer une session

Créer une nouvelle session

POST /v3/organizations/{org_id}/sessions

Créer une session

cURL

curl --request POST \
  --url https://api.devin.ai/v3/organizations/{org_id}/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "attachment_urls": [
    "<string>"
  ],
  "bypass_approval": true,
  "child_playbook_id": "<string>",
  "create_as_user_id": "<string>",
  "knowledge_ids": [
    "<string>"
  ],
  "max_acu_limit": 123,
  "platform": "<string>",
  "playbook_id": "<string>",
  "repos": [
    "<string>"
  ],
  "secret_ids": [
    "<string>"
  ],
  "session_links": [
    "<string>"
  ],
  "session_secrets": [
    {
      "key": "<string>",
      "value": "<string>",
      "sensitive": true
    }
  ],
  "structured_output_required": true,
  "structured_output_schema": {},
  "tags": [
    "<string>"
  ],
  "title": "<string>"
}
'

200

{
  "acus_consumed": 123,
  "created_at": 123,
  "org_id": "<string>",
  "pull_requests": [
    {
      "pr_state": "<string>",
      "pr_url": "<string>"
    }
  ],
  "session_id": "<string>",
  "status": "new",
  "tags": [
    "<string>"
  ],
  "updated_at": 123,
  "url": "<string>",
  "category": "bug_fixing",
  "child_session_ids": [
    "<string>"
  ],
  "is_archived": false,
  "origin": "webapp",
  "parent_session_id": "<string>",
  "playbook_id": "<string>",
  "service_user_id": "<string>",
  "status_detail": "working",
  "structured_output": {},
  "subcategory": "<string>",
  "title": "<string>",
  "user_id": "<string>"
}

​

Autorisations

Nécessite un compte de service disposant de l’autorisation ManageOrgSessions au niveau de l’organisation.

​

Autorisations supplémentaires pour les fonctions avancées

Fonctionnalité	Autorisation requise
create_as_user_id	ImpersonateOrgSessions

​

Usurpation d’identité d’un utilisateur

Le paramètre create_as_user_id permet de créer une session sur le compte d’un autre utilisateur. Cela nécessite :

1. Le compte de service doit disposer de l’autorisation ImpersonateOrgSessions
2. L’utilisateur cible doit être membre de l’organisation
3. L’utilisateur cible doit disposer de l’autorisation UseDevinSessions

Autorisations

Authorization · string · header · requis

Identifiant de compte de service (préfixe : cog_)

Paramètres de chemin

org_id · string | null · requis

ID de l’organisation (préfixe : org-)

Exemple:

"org-abc123def456"

Paramètres de requête

devin_id · string | null

Corps

application/json

prompt · string · requis

attachment_urls · string<uri>[] | null

Required string length: 1 - 2083

bypass_approval · boolean | null

child_playbook_id · string | null

create_as_user_id · string | null

knowledge_ids · string[] | null

max_acu_limit · integer | null

platform · string | null

Permet de remplacer la plateforme VM de la session (par ex. « windows »). Lorsqu’elle est omise (ou définie sur « inherit »), une session créée par un Devin parent hérite de la plateforme du parent ; sinon, la valeur par défaut de l’organisation est utilisée. Transmettez « default » pour forcer la valeur par défaut de l’organisation, quel que soit le parent. Toute autre valeur doit correspondre à une plateforme configurée pour votre organisation (sans distinction de casse) ; les valeurs non reconnues sont rejetées avec une erreur 400 dont le corps liste les libellés de plateforme disponibles pour l’organisation.

playbook_id · string | null

repos · string[] | null

secret_ids · string[] | null

session_links · string[] | null

session_secrets · SessionSecretInput · object[] | null

Show child attributes

structured_output_required · boolean | null

Lorsque la valeur est true (par défaut), l’agent DOIT appeler provide_structured_output avec is_final=true avant la fin de son tour. Lorsque la valeur est false, l’outil est disponible mais non obligatoire — son appel n’est pas garanti pour un tour donné.

structured_output_schema · Structured Output Schema · object

JSON Schema (Draft 7) pour la validation de la sortie structurée. Taille maximale : 64 Ko. Doit être autonome (aucune référence externe via $ref).

tags · string[] | null

title · string | null

Réponse

200

application/json

Réponse réussie

acus_consumed · number · requis

created_at · integer · requis

org_id · string · requis

pull_requests · SessionPullRequest · object[] · requis

Show child attributes

session_id · string · requis

status · enum<string> · requis

Options disponibles: new, claimed, running, exit, error, suspended, resuming

tags · string[] · requis

updated_at · integer · requis

url · string · requis

category · enum<string> | null

Catégorie de cas d’usage attribuée à la session, si la catégorisation a été effectuée. Renseigné uniquement sur les endpoints get/list.

Options disponibles: bug_fixing, ci_cd_and_devops, code_quality_and_security, code_review_and_analysis, data_and_automation, documentation_and_content, feature_development, migrations_and_upgrades, other, refactoring_and_optimization, research_and_exploration, unit_test_generation

child_session_ids · string[] | null

is_archived · boolean · défaut: false

origin · enum<string> | null

Origine depuis laquelle la session a été créée.

Options disponibles: webapp, slack, teams, api, linear, jira, automation, cli, desktop, other

parent_session_id · string | null

playbook_id · string | null

service_user_id · string | null

status_detail · enum<string> | null

Informations supplémentaires sur le statut actuel de la session. Lorsque status vaut 'running' : 'working' (travaille activement), 'waiting_for_user' (nécessite une saisie de l’utilisateur), 'waiting_for_approval' (en attente d’approbation d’une action en mode sécurisé) ou 'finished' (tâche terminée). Lorsque status vaut 'suspended' : le motif de la suspension, par exemple 'inactivity', 'user_request', 'usage_limit_exceeded', 'out_of_credits', 'out_of_quota', 'no_quota_allocation', 'payment_declined', 'org_usage_limit_exceeded', 'total_session_limit_exceeded' ou 'error'. Renseigné uniquement sur les endpoints get/list.

Options disponibles: working, waiting_for_user, waiting_for_approval, finished, inactivity, user_request, usage_limit_exceeded, out_of_credits, out_of_quota, no_quota_allocation, payment_declined, org_usage_limit_exceeded, total_session_limit_exceeded, error

structured_output · Structured Output · object

Sortie structurée validée provenant de la session. Renseignée uniquement sur les endpoints GET/list.

subcategory · string | null

Nom d’affichage de la sous-catégorie attribuée à la session. 'Other' lorsqu’une catégorie est définie, mais qu’aucune sous-catégorie n’a été attribuée ou résolue. Renseigné uniquement sur les endpoints get/list.

title · string | null

user_id · string | null