Submit an iteration directive

curl --request POST \
  --url https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from_checkpoint_seq": 123,
  "note": "<string>"
}
'

import requests

url = "https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive"

payload = {
    "from_checkpoint_seq": 123,
    "note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({from_checkpoint_seq: 123, note: '<string>'})
};

fetch('https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from_checkpoint_seq' => 123,
    'note' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive"

	payload := strings.NewReader("{\n  \"from_checkpoint_seq\": 123,\n  \"note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from_checkpoint_seq\": 123,\n  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from_checkpoint_seq\": 123,\n  \"note\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "attempt": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "directive": {},
    "directive_by_user_id": "<string>",
    "execution_id": "<string>",
    "pause_id": "<string>",
    "pending_calls": [
      {
        "call_id": "<string>",
        "tool_name": "<string>"
      }
    ],
    "seq": 123,
    "session_id": "<string>",
    "withheld_outputs": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "timings_ms": {},
    "pagination": {
      "has_more": true,
      "next_cursor": "<string>"
    },
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Iteration Sessions

Submit an iteration directive

Resolves one AWAITING_DIRECTIVE pause: CONTINUE resumes with the withheld output delivered verbatim (free — resumes never bill); FINISH_RUN resumes with a wrap-up note so the agent concludes; RESTART_RUN abandons the parked attempt and starts a fresh one from the beginning against the agent’s current (just-edited) config — bills like a normal run; RESTART_FROM_CHECKPOINT also starts a fresh attempt (same billing), but forks the agent’s model thread at an earlier checkpoint of this attempt — the kept steps’ tool calls and outputs are already in the thread and are NOT re-executed; the agent re-decides only from the step after the checkpoint, under the current config. from_checkpoint_seq picks the checkpoint (default: the last one before this pause). Side effects the discarded tail already caused are not undone. 400 when no such checkpoint exists or the agent’s model changed since it (fall back to RESTART_RUN); CANCEL abandons the parked attempt and leaves the session open. 409 when the pause already received a directive. CONTINUE/FINISH_RUN require a parked tool output (an EVERY_STEP pause, not a RUN_COMPLETE one).

POST

public-api

iteration-sessions

{session_id}

pauses

{pause_id}

directive

Submit an iteration directive

curl --request POST \
  --url https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from_checkpoint_seq": 123,
  "note": "<string>"
}
'

import requests

url = "https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive"

payload = {
    "from_checkpoint_seq": 123,
    "note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({from_checkpoint_seq: 123, note: '<string>'})
};

fetch('https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from_checkpoint_seq' => 123,
    'note' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive"

	payload := strings.NewReader("{\n  \"from_checkpoint_seq\": 123,\n  \"note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from_checkpoint_seq\": 123,\n  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.neoagent.io/public-api/iteration-sessions/{session_id}/pauses/{pause_id}/directive")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from_checkpoint_seq\": 123,\n  \"note\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "attempt": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "directive": {},
    "directive_by_user_id": "<string>",
    "execution_id": "<string>",
    "pause_id": "<string>",
    "pending_calls": [
      {
        "call_id": "<string>",
        "tool_name": "<string>"
      }
    ],
    "seq": 123,
    "session_id": "<string>",
    "withheld_outputs": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "timings_ms": {},
    "pagination": {
      "has_more": true,
      "next_cursor": "<string>"
    },
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Authorizations

Authorization

string

header

required

Authorization: Bearer <token> where <token> is either a neo_sk_<env>_<secret> API key (service account) or a Microsoft Entra ID access token (dashboard user).

Path Parameters

pause_id

string

required

session_id

string

required

Body

application/json

type

enum<string>

required

Available options:

CONTINUE,

RESTART_RUN,

RESTART_FROM_CHECKPOINT,

FINISH_RUN,

CANCEL

from_checkpoint_seq

integer | null

note

string | null

Response

Success.

data

PublicIterationPause · object

required

Show child attributes

Get started

Endpoints

Submit an iteration directive

Authorizations

Path Parameters

Body

Response