Gobare Agent API

Run a coding agent from your own code. Not a model that writes code back to you — an agent with a computer, that writes files, runs them, and leaves what it built at a URL you can open. The agent is pi — the open-source coding agent, MIT-licensed, running unmodified inside each session. Gobare is the computer around it and the API in front of it. If you have used another agent API, the request shapes will look familiar; that is deliberate. What is different is what a session is — a real computer — and three things that are true of it at once:


You can log into it.	Open a shell on the machine the agent is working on, check what it did, fix it, and hand it back → Take over the machine
What it builds stays reachable.	A published app pauses when nobody is using it and wakes for the next visitor → Publish and wake
The model is yours to choose.	Nine providers or any compatible endpoint, on your own account. You pay your provider for tokens and Gobare for the computer → model credentials

More in How Gobare is different, including what it does not do yet. Don’t write code? Build in the Console instead.

A minute, start to finish

This asks for something to be built, waits, and prints an address. Nothing is elided — it is the whole program.

SESSION=$(curl -s -X POST https://api.gobare.dev/v1/sessions \
  -H "Authorization: Bearer $GOBARE_TOKEN" -H 'content-type: application/json' \
  -d '{"agent":{"model":"MiniMax-M3"},
       "input":"Build a small expense tracker web page — a form to add an expense, a running total, saved in localStorage. Serve it on port 8000 and keep the server running."}' \
  | jq -r .id)

# The turn appears a moment after the session, so the list is briefly empty —
# and an empty list means it has not started, not that it has finished.
until [ "$(curl -s "https://api.gobare.dev/v1/sessions/$SESSION/turns?limit=1" \
  -H "Authorization: Bearer $GOBARE_TOKEN" | jq -r '.data[0].status // "working"')" != "working" ]; do sleep 5; done

curl -s -X POST "https://api.gobare.dev/v1/sessions/$SESSION/preview" \
  -H "Authorization: Bearer $GOBARE_TOKEN" -H 'content-type: application/json' -d '{}' | jq -r .url

const API = "https://api.gobare.dev";
const AUTH = { Authorization: `Bearer ${process.env.GOBARE_TOKEN}`, "content-type": "application/json" };

const call = async (method: string, path: string, body?: unknown) =>
  (await fetch(API + "/v1" + path, { method, headers: AUTH, body: body && JSON.stringify(body) })).json();

const session = await call("POST", "/sessions", {
  agent: { model: "MiniMax-M3" },
  input: "Build a small expense tracker web page — a form to add an expense, a running " +
         "total, saved in localStorage. Serve it on port 8000 and keep the server running.",
});

for (;;) {
  const [turn] = (await call("GET", `/sessions/${session.id}/turns?limit=1`)).data;
  if (turn && turn.status !== "working") break;
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

console.log((await call("POST", `/sessions/${session.id}/preview`, {})).url);

import json, os, time, urllib.request

API, TOKEN = "https://api.gobare.dev", os.environ["GOBARE_TOKEN"]
AUTH = {"Authorization": "Bearer " + TOKEN, "content-type": "application/json"}

def call(method, path, body=None):
    return json.load(urllib.request.urlopen(urllib.request.Request(
        API + "/v1" + path, data=json.dumps(body).encode() if body is not None else None,
        headers=AUTH, method=method)))

session = call("POST", "/sessions", {
    "agent": {"model": "MiniMax-M3"},
    "input": "Build a small expense tracker web page — a form to add an expense, a running "
             "total, saved in localStorage. Serve it on port 8000 and keep the server running.",
})

while True:
    turns = call("GET", f"/sessions/{session['id']}/turns?limit=1")["data"]
    if turns and turns[0]["status"] != "working":
        break
    time.sleep(5)

print(call("POST", f"/sessions/{session['id']}/preview", {})["url"])

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

const api = "https://api.gobare.dev"

func call(method, path string, body any) map[string]any {
	var reader io.Reader
	if body != nil {
		b, _ := json.Marshal(body)
		reader = bytes.NewReader(b)
	}
	req, _ := http.NewRequest(method, api+"/v1"+path, reader)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("GOBARE_TOKEN"))
	req.Header.Set("content-type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	var out map[string]any
	json.NewDecoder(resp.Body).Decode(&out)
	return out
}

func main() {
	session := call("POST", "/sessions", map[string]any{
		"agent": map[string]any{"model": "MiniMax-M3"},
		"input": "Build a small expense tracker web page — a form to add an expense, a running " +
			"total, saved in localStorage. Serve it on port 8000 and keep the server running.",
	})
	id := session["id"].(string)

	for {
		turns := call("GET", "/sessions/"+id+"/turns?limit=1", nil)
		data, _ := turns["data"].([]any)
		if len(data) > 0 && data[0].(map[string]any)["status"] != "working" {
			break
		}
		time.Sleep(5 * time.Second)
	}

	preview := call("POST", "/sessions/"+id+"/preview", map[string]any{})
	fmt.Println(preview["url"])
}

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

public class Quickstart {
  static final String API = "https://api.gobare.dev";
  static final HttpClient client = HttpClient.newHttpClient();
  static final String TOKEN = System.getenv("GOBARE_TOKEN");

  static String call(String method, String path, String body) throws Exception {
    var builder = HttpRequest.newBuilder(URI.create(API + "/v1" + path))
        .header("Authorization", "Bearer " + TOKEN)
        .header("content-type", "application/json");
    builder = body == null
        ? builder.method(method, HttpRequest.BodyPublishers.noBody())
        : builder.method(method, HttpRequest.BodyPublishers.ofString(body));
    return client.send(builder.build(), HttpResponse.BodyHandlers.ofString()).body();
  }

  // No JSON library in the standard library, so this reads the one field each
  // step needs rather than pulling in a dependency for it.
  static String field(String json, String key) {
    int i = json.indexOf("\"" + key + "\"");
    int start = json.indexOf('"', json.indexOf(':', i)) + 1;
    return json.substring(start, json.indexOf('"', start));
  }

  public static void main(String[] args) throws Exception {
    String body = "{\"agent\":{\"model\":\"MiniMax-M3\"}," +
        "\"input\":\"Build a small expense tracker web page — a form to add an expense, " +
        "a running total, saved in localStorage. Serve it on port 8000 and keep the server running.\"}";
    String session = call("POST", "/sessions", body);
    String id = field(session, "id");

    while (true) {
      String turns = call("GET", "/sessions/" + id + "/turns?limit=1", null);
      if (turns.contains("\"status\"") && !field(turns, "status").equals("working")) break;
      Thread.sleep(Duration.ofSeconds(5));
    }

    String preview = call("POST", "/sessions/" + id + "/preview", "{}");
    System.out.println(field(preview, "url"));
  }
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

const string api = "https://api.gobare.dev";
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("GOBARE_TOKEN"));

async Task<JsonElement> Call(HttpMethod method, string path, object? body = null)
{
    var request = new HttpRequestMessage(method, api + "/v1" + path);
    if (body != null)
        request.Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
    var response = await client.SendAsync(request);
    return JsonDocument.Parse(await response.Content.ReadAsStringAsync()).RootElement;
}

var session = await Call(HttpMethod.Post, "/sessions", new
{
    agent = new { model = "MiniMax-M3" },
    input = "Build a small expense tracker web page — a form to add an expense, a running " +
            "total, saved in localStorage. Serve it on port 8000 and keep the server running.",
});
var id = session.GetProperty("id").GetString();

while (true)
{
    var turns = await Call(HttpMethod.Get, $"/sessions/{id}/turns?limit=1");
    var data = turns.GetProperty("data");
    if (data.GetArrayLength() > 0 && data[0].GetProperty("status").GetString() != "working") break;
    await Task.Delay(TimeSpan.FromSeconds(5));
}

var preview = await Call(HttpMethod.Post, $"/sessions/{id}/preview", new { });
Console.WriteLine(preview.GetProperty("url").GetString());

require "net/http"
require "json"
require "uri"

API = "https://api.gobare.dev"
TOKEN = ENV.fetch("GOBARE_TOKEN")

def call(method, path, body = nil)
  uri = URI(API + "/v1" + path)
  req = method == "GET" ? Net::HTTP::Get.new(uri) : Net::HTTP::Post.new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  req["content-type"] = "application/json"
  req.body = JSON.generate(body) if body
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
  JSON.parse(res.body)
end

session = call("POST", "/sessions", {
  agent: { model: "MiniMax-M3" },
  input: "Build a small expense tracker web page — a form to add an expense, a running " \
         "total, saved in localStorage. Serve it on port 8000 and keep the server running.",
})

loop do
  turns = call("GET", "/sessions/#{session['id']}/turns?limit=1")["data"]
  break if turns.any? && turns[0]["status"] != "working"
  sleep 5
end

preview = call("POST", "/sessions/#{session['id']}/preview", {})
puts preview["url"]

https://s-a23a2eb878db4d8bbefd.gobare.dev

Open it. There is a working page there, served from the computer the agent was given — a form, a running total, saved in the browser. Forty-nine seconds on one run of this, a hundred and eleven on another; the difference is how long the sandbox took to come up. All seven of the programs above ran this exact scenario against production — each produced a session, a preview URL, and a page that loaded. None of them need a client library: this API is plain HTTP and JSON, so each is standard library only, the same rule the guides follow. You need a token for this. It takes a minute and the quickstart has it.

What just happened

Five nouns, and they nest:

Agent — a named configuration: model, instructions, tools. Optional; a session can carry its own.
Session — one cloud computer. Its workspace persists between rounds and survives being paused.
Turn — one piece of work, from your message until it settles.
Items — the record: messages, tool calls, file changes.
Events — the same, as it happens: streamable, resumable.
Artifacts — files it published; they outlive the computer.
Preview — a port it serves, optionally at a public URL.

The session is the thing to hold on to. Everything else is reached through it, and a session you created yesterday still answers today — its computer may have been reclaimed and rebuilt, and the conversation does not restart.

Why this and not a model API

A model API returns text. You would still be writing the part that actually runs: a sandbox and its lifecycle, an agent loop, tool dispatch, file capture, streaming, resumption after a dropped connection, and somewhere for a person to approve something before it happens. That list is the product. It is also why there is no sandbox-free mode — for a coding agent the workspace is not an accessory. What Gobare deliberately does not do: sell you inference, choose your model, or hold your conversation state in your process. The first is why you connect your own key; the last is why a session is a URL you can come back to rather than an object you keep in memory. Coming from another Agents API? design-decisions.md lists where this one diverges and why — queueing versus steering, durable versus transient events, and what completed does not mean. Weighing OpenAI’s Agents API against the other options as a whole? OpenAI Agents API alternatives compares the hosted, wire-compatible and self-hosted choices, with the request shapes side by side and a field-by-field migration map.

Common tasks


Run one task and collect the result	quickstart.md
Put it in a service and keep it running	production-integration.md
Call it from TypeScript, with types	typescript.md
Call it from Python, with types	python.md
Let the agent call your own code	required-actions.md
Be told when it finishes, rather than waiting	webhooks.md
Put what it built on a public URL	preview.md
Look up a field or an endpoint	objects.md · reference.md
Work out why something looks wrong	troubleshooting.md

Base URL: https://api.gobare.dev — https://app.gobare.dev serves the same API and is what the Console uses.

Every page

Page	Read it when
pi.md	You want to know which agent actually runs in a session, and what Gobare adds around it
why-gobare.md	You have seen agent APIs before and want to know what this one gives you that they do not
without-code.md	You want something built for you, not an API
quickstart.md	First time. Token to completed turn, in one page
production-integration.md	It works, and now it has to keep working
typescript.md	You are past `curl` and putting this in a service
python.md	The same, in Python
AGENTS.md	The client is an agent. The whole build order in one pass, with a check after every step and a self-test at the end
model-credentials.md	You want to connect a model without opening the Console
sessions.md	You want a session to hold your repo, files, secrets or limits
saved-agents.md	You want every session in one part of your product to start the same way
input.md	You want to send the agent a message, a result, a steer or a stop
events.md	You want to watch a session instead of polling it
webhooks.md	You want to be told rather than to watch
preview.md	You want what the agent built to be reachable by other people
tools.md	You want to give the agent your functions, or an MCP server
required-actions.md	You want the agent to call your code
idempotency.md	Your caller retries, and you need it not to act twice
pagination.md	A collection has more rows than one page, or you need to find a session by your own id
troubleshooting.md	Something looks wrong and you want it by symptom, not by endpoint
errors.md	Something returned a code you have not seen
limits.md	You are planning load, or you got a 429
changelog.md	You want to know what changed, and when
design-decisions.md	You want to know why the API behaves as it does

Those pages describe the parts. Guides put them together as scenarios you can copy, and Integrations connect a session to systems you already run — Temporal, agent frameworks, GitHub Actions, Slack, Cloudflare Workers and billing. The machine-readable reference is GET /v1/openapi.json — OpenAPI 3.1, no token needed, because it describes the API rather than holding data in it. Take it before you read anything else here: it carries every field constraint and a real example payload for every event type, which is the part prose is worst at. Every /v1 response points at it:

link: </v1/openapi.json>; rel="service-desc"; type="application/json"

That is there for callers who cannot read this page — an agent has the response in front of it and no way to guess a URL, and one header on a call it was already making is worth more than a paragraph it will never see. It is generated from the same route table the server matches against, so it cannot describe an endpoint that does not exist.

How these pages stay true

The product repository is the source. This directory is checked against the code it describes — ceilings against the constants that enforce them, error codes against their statuses, both event vocabularies — so a page cannot quietly drift from the API. These pages are published as a site at docs.gobare.dev, built from this directory by deploy/publish-docs-site.sh. A copy of the markdown also goes to gobare_tools via scripts/publish-api-docs.sh, which refuses to run if the check above does not pass.

Scope

Gobare brings your own model key. The API does not sell you inference — it runs an agent against a model credential your organization has already connected, on a sandbox Gobare provides. There is no request field for a model provider, because the provider is a property of the credential. There is also no sandbox-free mode. For a coding agent the workspace is the product, not an accessory, so every session has one.

Start here

Running a session

Guides

Integrations

Client libraries

When things go wrong

API reference

About this API

Endpoints

A minute, start to finish

What just happened

Why this and not a model API

Common tasks

Every page

How these pages stay true

Scope

​A minute, start to finish

​What just happened

​Why this and not a model API

​Common tasks

​Every page

​How these pages stay true

​Scope

A minute, start to finish

What just happened

Why this and not a model API

Common tasks

Every page

How these pages stay true

Scope