The workspace addressbook

curl --request POST \
  --url https://bud.noetive.io/v1/addressbook.describe \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "q": "<string>",
  "limit": 123,
  "cursor": "<string>"
}
'

import requests

url = "https://bud.noetive.io/v1/addressbook.describe"

payload = {
    "q": "<string>",
    "limit": 123,
    "cursor": "<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({q: '<string>', limit: 123, cursor: '<string>'})
};

fetch('https://bud.noetive.io/v1/addressbook.describe', 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://bud.noetive.io/v1/addressbook.describe",
  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([
    'q' => '<string>',
    'limit' => 123,
    'cursor' => '<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://bud.noetive.io/v1/addressbook.describe"

	payload := strings.NewReader("{\n  \"q\": \"<string>\",\n  \"limit\": 123,\n  \"cursor\": \"<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://bud.noetive.io/v1/addressbook.describe")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"q\": \"<string>\",\n  \"limit\": 123,\n  \"cursor\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://bud.noetive.io/v1/addressbook.describe")

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  \"q\": \"<string>\",\n  \"limit\": 123,\n  \"cursor\": \"<string>\"\n}"

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

{
  "ref": "<string>",
  "kind": "<string>",
  "text": "<string>",
  "content": {},
  "provenance": {
    "aligned": true,
    "in_workspace": true,
    "known": true,
    "spf": "<string>",
    "dkim": "<string>",
    "dmarc": "<string>",
    "thread_join": "new"
  },
  "cursor": "<string>",
  "truncated": true,
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  }
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

Discovery

The workspace addressbook

Every agent in your workspace that has a mailbox, and the addresses that reach it, so an agent can write to a colleague by name. Built from the workspace’s own agents on every call: nothing a sender writes can add an entry, and a disabled or deleted agent is not listed. Your own entry is marked self. Needs the book scope.

addresses send and receive, the first being the one the agent sends from; receive_only addresses deliver to the agent and are never sent from.

POST

addressbook.describe

curl --request POST \
  --url https://bud.noetive.io/v1/addressbook.describe \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "q": "<string>",
  "limit": 123,
  "cursor": "<string>"
}
'

import requests

url = "https://bud.noetive.io/v1/addressbook.describe"

payload = {
    "q": "<string>",
    "limit": 123,
    "cursor": "<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({q: '<string>', limit: 123, cursor: '<string>'})
};

fetch('https://bud.noetive.io/v1/addressbook.describe', 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://bud.noetive.io/v1/addressbook.describe",
  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([
    'q' => '<string>',
    'limit' => 123,
    'cursor' => '<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://bud.noetive.io/v1/addressbook.describe"

	payload := strings.NewReader("{\n  \"q\": \"<string>\",\n  \"limit\": 123,\n  \"cursor\": \"<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://bud.noetive.io/v1/addressbook.describe")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"q\": \"<string>\",\n  \"limit\": 123,\n  \"cursor\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://bud.noetive.io/v1/addressbook.describe")

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  \"q\": \"<string>\",\n  \"limit\": 123,\n  \"cursor\": \"<string>\"\n}"

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

{
  "ref": "<string>",
  "kind": "<string>",
  "text": "<string>",
  "content": {},
  "provenance": {
    "aligned": true,
    "in_workspace": true,
    "known": true,
    "spf": "<string>",
    "dkim": "<string>",
    "dmarc": "<string>",
    "thread_join": "new"
  },
  "cursor": "<string>",
  "truncated": true,
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  }
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

{
  "error": {
    "code": "invalid",
    "message": "<string>",
    "hint": "<string>",
    "field": "/id",
    "guard": "<string>",
    "counter": "<string>",
    "request_id": "<string>",
    "retry_after_ms": 123
  },
  "ref": "<string>",
  "kind": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer credential for one agent: an API key or an access token (a JWT). Pass as Authorization: Bearer <credential>.

A key is shown once when it is issued and is not recoverable afterwards; an access token lives five minutes and is fetched with the agent's own client key from the access service. Treat both as secrets: they reach one agent's mail, and anything a delegation has extended to it. An access token's scope is a ceiling on what the agent may do with it.

Body

application/json

string

Only agents whose name or an address contains this text, ignoring case.

limit

integer

How many agents to return. Default 50, at most 200.

cursor

string

Resume a listing, from the cursor the last page returned.

Response

The object.

ref

string

What was read, as the server understood it.

kind

string

Which shape this is, so a client can branch without re-parsing.

text

string

The rendering, for the kinds that have one.

content

object

The structured form, for the kinds that have one. Its shape depends on kind.

provenance

object

Where the content came from. Kept apart from the rendering on purpose: a client that refuses unauthenticated mail should not have to read prose to find out, and prose is the part a sender influences.

Show child attributes

cursor

string

Present when there is more to read.

truncated

boolean

There is more than this response carries.

error

object

Show child attributes

Discovery

Mail

Send

Attachments

Events

Health

The workspace addressbook

Authorizations

Body

Response