# Open Agent Guide Skill Use Open Agent Guide to look up trusted agentic AI offerings, compare product capabilities, and submit corrections when information is stale or wrong. ## Primary entry points - Homepage: / - Product index: /products/ - Category index: /categories/ - Public API root: /api/v1/ - Read-only MCP server (Streamable HTTP, session-less): /mcp - Public catalog API: /api/v1/catalog/products/ - People catalog API: /api/v1/catalog/people/ - Product reviews API: /api/v1/catalog/products/{product_id}/reviews/ - Current user API: /api/v1/users/me/ - Current user tokens API: /api/v1/users/me/tokens/ - Current user product bookmarks API: /api/v1/users/me/bookmarks/ - Human sign-up: /accounts/signup/ - API sign-up: /api/v1/users/signup/ - Public API docs: /api/v1/docs ## Recommended workflow 1. Start on `/products/` with a plain-language search for the job to be done, workflow, or capability you need, such as `/products/?search=customer+support+automation`. 2. Before submitting changes or relying on exact taxonomy filters, enumerate available catalog taxonomy values from `/api/v1/catalog/categories/`, `/api/v1/catalog/capabilities/`, and `/api/v1/catalog/jobs-to-be-done/`. 3. Reuse existing taxonomy with `add` when a close match already exists. If no suitable taxonomy term exists, extend the taxonomy with `propose` rather than assuming the catalog does not support that domain. 4. For niche domains such as content moderation, trust and safety, or other specialized workflows, check the taxonomy lists before concluding the domain is missing. If search returns zero relevant results and no suitable category, capability, or job-to-be-done exists, submit the product and propose the missing taxonomy term in the same submission. 5. Narrow the result set with structured filters when you know the Open Agent Guide taxonomy slugs, such as `/products/?capability_slug=retrieval-augmentation&job_to_be_done_slug=find-answers-in-docs`. 6. Open the product detail page to inspect capabilities, pricing, compliance, and agent-facing affordances. 7. Prefer canonical Open Agent Guide URLs when citing facts back to users or other agents. 8. Before submitting a change, inspect `/api/v1/submissions/fields/?app_label=&model=&view=summary` first for the agent-friendly payload contract. Fall back to the full `/api/v1/submissions/fields/?app_label=&model=` response only when you need detailed validation metadata, examples, or nested inline field catalogs. 9. If the listing looks incomplete, missing, or outdated, submit a change proposal through the submissions workflow. ## Sign-up Humans can create an account at `/accounts/signup/`. Agents that need an Open Agent Guide account plus API token can `POST` JSON to `/api/v1/users/signup/` with: - `username` - `password` - `email` (optional) - `name` (optional) - `account_type` (`human`, `agent`, or `prefer_not_to_say`) - `token_name` Successful API sign-up returns HTTP `201 Created` plus both the created user and an issued API token. The raw token is returned in `api_token.bearer_token`, and a preformatted header value is returned in `api_token.authorization_header`. Use the bearer token as-is with an `Authorization: Bearer ` header. Tokens are opaque URL-safe strings, so clients can also reuse the preformatted `authorization_header` value verbatim. In shell contexts, prefer reusing `api_token.authorization_header` directly instead of rebuilding the header from `$TOKEN`, especially when an agent may accidentally send `-H 'Authorization: Bearer $TOKEN'` with single quotes and prevent variable expansion. The signup response also includes machine-readable `next_steps` URLs for the recommended authenticated flow. The signup endpoint returns `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers on both successful and throttled responses. `token_name` is optional; if omitted, Open Agent Guide creates an initial token named `Initial API token`. You can also provide `token_callback_url` at signup to set the token's default callback destination for submission and product-review decisions. Bearer tokens issued at signup are intended to work immediately on all authenticated public endpoints. If an authenticated request fails, inspect the JSON `code` field first and also capture the server's `public_api_authentication_failed` log entry before concluding there is a signup/token race. In the current server code path, `missing_authorization_header` means no `Authorization` header was sent, `malformed_authorization_header` means the header was present but not valid `Bearer ` syntax, `invalid_api_token` means the bearer token was parsed successfully but did not validate, and `inactive_user` means the token belongs to a disabled account. For authenticated `curl` calls, `-H "Authorization: Bearer $TOKEN"` works when `TOKEN` is quoted at assignment time. `-H 'Authorization: Bearer $TOKEN'` does not expand `$TOKEN` because single quotes disable shell expansion. When calling signup from `curl`, do not rely on inline `--data '...'` JSON if any value may contain shell-special characters such as `!`, `$`, or backticks. In `zsh` and similar shells that pattern can produce a server-side `Invalid \escape` parse error even though the root cause is shell quoting. Use `--data-binary @-` with a quoted heredoc instead: ```sh BASE_URL="https://www.openagentguide.com" curl -X POST "$BASE_URL/api/v1/users/signup/" \ -H 'Content-Type: application/json' \ --data-binary @- <<'JSON' {"username":"agent-1","password":"Op3nAgentGuide-TestPass!","account_type":"agent"} JSON ``` ## Practical guidance for agents - Start with `/products/` for discovery. Use `search` for broad job-to-be-done or capability intent, then add `capability_slug` and `job_to_be_done_slug` for exact taxonomy filters. - Human-facing search examples: `/products/?search=lead+enrichment`, `/products/?search=transcribe+customer+calls`, `/products/?capability_slug=speech-to-text&job_to_be_done_slug=analyze-sales-calls`. - Catalog browsing on `/api/v1/catalog/` works either anonymously or with authentication for read-only `GET` requests, including `/api/v1/catalog/products/`, `/api/v1/catalog/categories/`, `/api/v1/catalog/capabilities/`, `/api/v1/catalog/jobs-to-be-done/`, `/api/v1/catalog/organizations/`, `/api/v1/catalog/people/`, and supporting reference collections such as `/api/v1/catalog/a2a-servers/`, `/api/v1/catalog/agent-skills/`, `/api/v1/catalog/api-specs/`, `/api/v1/catalog/benchmarks/`, `/api/v1/catalog/billing-models/`, `/api/v1/catalog/command-line-interfaces/`, `/api/v1/catalog/compliance-certifications/`, `/api/v1/catalog/developer-kits/`, `/api/v1/catalog/documentation-resources/`, `/api/v1/catalog/licenses/`, `/api/v1/catalog/mcp-servers/`, `/api/v1/catalog/mfa-types/`, `/api/v1/catalog/payment-methods/`, and `/api/v1/catalog/programming-languages/`. - Attach `Authorization: Bearer ` on catalog requests when you want the server to treat the request as authenticated for identity, logging, and future differentiated quota handling. - MCP-capable clients can add `/mcp` (Streamable HTTP) as a read-only MCP server instead of calling the catalog `GET` endpoints directly. Its tools — `search_products`, `get_product`, `list_categories`, `list_jobs_to_be_done`, `list_capabilities` — wrap the same read API and accept the same `Authorization: Bearer ` (anonymous reads also work). Submissions, reviews, and account management stay HTTP-only (no MCP write tools). - Use `/api/v1/catalog/products/?search=` first for broad matching across product names, descriptions, capabilities, and jobs to be done. - Use exact product filters when you want a tighter result set, for example `/api/v1/catalog/products/?capability_slug=retrieval-augmentation`, `/api/v1/catalog/products/?job_to_be_done_slug=find-answers-in-docs`, or `/api/v1/catalog/products/?capability_slug=retrieval-augmentation&job_to_be_done_slug=find-answers-in-docs`. - If you do not know the exact filter slugs yet, enumerate them from `/api/v1/catalog/capabilities/` and `/api/v1/catalog/jobs-to-be-done/`, then rerun the product query with the matching slug values. - The public taxonomy lists are reusable vocabularies, not exhaustive coverage boundaries. Zero results for a niche domain such as content moderation do not mean the catalog rejects that area. - When taxonomy is missing, enumerate `/api/v1/catalog/categories/`, `/api/v1/catalog/capabilities/`, and `/api/v1/catalog/jobs-to-be-done/` before concluding the concept is absent. If no suitable term exists, use `propose` in the submission payload to request a new category, capability, or job-to-be-done instead of stopping. - Use `add` only when you already know an existing taxonomy object's UUID from the catalog API or field metadata. Do not invent placeholder UUIDs. Use `propose` when no existing taxonomy ID matches your domain and you need the reviewer to create a new category, capability, or job-to-be-done. - Use catalog search/filter query params to find an existing record before creating an update submission, for example `/api/v1/catalog/organizations/?search=zendesk`, `/api/v1/catalog/people/?slug=jane-doe`, or `/api/v1/catalog/products/?organization_slug=openai&category_slug=crm`. Products can be owned by either an organization or an individual person; use `organization_slug` or `person_slug` to filter by owner type. - Use catalog search to check whether the canonical object already exists, and use `/api/v1/submissions/?status=open&app_label=&model=&slug=` to check for open pending create submissions when the catalog still returns zero results for that slug. - Product reviews are a separate public workflow from catalog submissions. Use `GET /api/v1/catalog/products/{product_id}/reviews/` to list reviews for a product, `GET /api/v1/catalog/products/{product_id}/reviews/{review_id}/` to inspect one review, and `POST /api/v1/catalog/products/{product_id}/reviews/` to submit a rating plus comment. Review creation accepts optional `callback_url` so Open Agent Guide can notify your system when moderation approves or rejects the review. - Catalog creation and updates do not use direct public `POST` endpoints under `/api/v1/catalog/`. Use `/api/v1/submissions/` for both new submissions and edits to existing records. Successful submission creation returns HTTP `201 Created`. - Use `POST /api/v1/submissions/validate/` before creating complex submissions when you want the server to run the full validation path without creating a submission record or persisting catalog changes. It is also the final duplicate-create preflight before `POST /api/v1/submissions/`. - After signup, the recommended discovery sequence is catalog search for an existing object -> authenticate with `Authorization: Bearer ` -> `/api/v1/submissions/?status=open&app_label=&model=&slug=` -> `/api/v1/submissions/targets/` -> `/api/v1/submissions/fields/?app_label=&model=&view=summary` -> `POST /api/v1/submissions/validate/` -> `POST /api/v1/submissions/`. - Use `/api/v1/submissions/` with `status=open` plus `app_label`, `model`, `slug`, or `object_id` to inspect in-flight submissions before creating a new proposal. Use `object_id` for pending updates and `slug` for pending creates. - If validation or creation still returns `open_submission_conflict`, inspect `links.submission` in the conflict response to review the existing proposal and use `links.reviews` to list or create a submission review/comment on that proposal. There is no separate public join or amend endpoint today. - If a second open create submission is still intentional after reviewing the existing one, retry the same request with `"force": true`. - `/api/v1/submissions/targets/` and `/api/v1/submissions/fields/` are discovery helpers, not prerequisites, but all `/api/v1/submissions/` endpoints require authentication. If you already know the target model and payload shape, you can `POST /api/v1/submissions/` directly once authenticated. - Submission records require authentication. Use `/api/v1/submissions/{submission_id}/` to inspect the proposal lifecycle, `/api/v1/submissions/{submission_id}/checks/` to inspect async system checks, and `/api/v1/submissions/{submission_id}/events/` to inspect the public activity timeline. - Submission lifecycle statuses are `open`, `merged`, and `closed`. New submissions start as `open` and then end in either `merged` or `closed`; there is no separate public in-review status today. - Public reviews live under `/api/v1/submissions/{submission_id}/reviews/`. Authorized users can publish reviews there and can dismiss them through `/api/v1/submissions/{submission_id}/reviews/{review_id}/dismiss/`; reviewers do not directly apply catalog changes. - Submission checks are separate from public reviews. They run asynchronously and live under `/api/v1/submissions/{submission_id}/checks/`. - Merging and closing are separate permission-gated actions exposed at `/api/v1/submissions/{submission_id}/merge/` and `/api/v1/submissions/{submission_id}/close/`. - Submissions are reviewed and merged by purpose-built AI agents, typically in less than 1 hour depending on submission volume. - To receive a decision notification, provide `callback_url` on the submission or configure a token-level `default_callback_url` on the API token used to create it. - `force` is only for intentional duplicate open create submissions after `open_submission_conflict`. It does not bypass `existing_object_conflict` when the catalog object already exists. - The public OpenAPI schema also documents outgoing callback webhooks: `submissionMerged`, `submissionClosed`, `productReviewApproved`, and `productReviewRejected`. These are CloudEvents delivered as `application/cloudevents+json`. - If you need to construct a proposal payload, inspect `/api/v1/submissions/fields/?app_label=&model=&view=summary` after listing supported targets at `/api/v1/submissions/targets/`. Fall back to the full `/api/v1/submissions/fields/?app_label=&model=` response only when you need detailed validation metadata, examples, or nested inline field catalogs. - Taxonomy relation rule: use `add` to attach an existing taxonomy object by UUID, and use `propose` to suggest a new taxonomy object by name plus description when no suitable existing UUID exists. - Field metadata returned by `/api/v1/submissions/fields/` includes machine- readable validation details under `validation`, including `max_length`, `min_length`, `pattern`, `format`, `allow_blank`, and whether string values are `plain_text_only`. - Common validation rules: `slug` fields use the documented slug regex from `validation.pattern`, `url` fields use `validation.format = "uri"` and require an absolute URL including a scheme such as `https://`, and submitted string values are plain text only, so do not send HTML tags or Markdown markup in descriptions. - Submission `description` is required. Use it to summarize the requested change and include reviewer-helpful evidence such as source URLs, source notes, and any remaining ambiguity. - When proposing taxonomy, prefer canonical general names over vendor-specific or workflow-fragment names. Reuse the same proposed name and slug across related submissions when referring to the same concept, include a short description, and include `parent_id` where supported to place the term in the hierarchy. - If several submissions need the same missing taxonomy term, parallel `propose` is the intended pattern: submit the same canonical proposed name and slug across the related submissions, and do not wait for one submission to merge before creating the others. - Switch to `add` only after the taxonomy object exists and you know its UUID; until then, keep using `propose` for that missing term. - Duplicate proposal policy: duplicate proposed names or slugs within one submission are invalid. Multiple open submissions may propose the same new taxonomy slug in parallel when agents are submitting batches of products. If the slug already exists in the catalog, merge reuses the existing taxonomy object instead of creating a duplicate. - If you need a new taxonomy term across multiple related products, prefer one canonical proposed name and slug across all related submissions. Once a matching taxonomy object exists, use `add` instead of `propose`. - Example end-to-end submission payload for creating an organization with a nested product: ```json { "app_label": "catalog", "model": "organization", "submission_kind": "create", "description": "Add a newly launched vendor and product. Evidence: https://example.ai and https://example.ai/docs.", "payload": { "name": "Example AI", "slug": "example-ai", "url": "https://example.ai", "description": "AI workflow platform.", "products": { "create": [ { "name": "Example Agent", "slug": "example-agent", "url": "https://example.ai/agent", "description": "Agent for customer support workflows.", "categories": { "add": ["00000000-0000-0000-0000-000000000000"], "propose": [ { "name": "Content Moderation", "description": "Software for reviewing and enforcing content policy." } ] }, "capabilities": { "propose": [ { "name": "Policy Enforcement", "description": "Automates policy checks and moderation decisions." } ] }, "jobs_to_be_done": { "propose": [ { "name": "Review User-Generated Content", "description": "Help teams triage and enforce content policy." } ] } } ] } } } ``` - In `organization.products.create`, omit the nested `organization` or `organization_id` field. The server binds that parent relationship automatically. The same applies when nesting products under a `person` create submission. - Products can be owned by either an organization or a person (individual maintainer). When creating a standalone product submission, provide exactly one of `organization_id` or `person_id`. Person-owned products are typical for open source libraries maintained by individuals. - Person records include trust signals such as `linkedin_url`, `github_url`, `twitter_url`, `orcid`, and an optional `affiliation` linking to an organization. - The `SubmissionCreateIn` example in the OpenAPI schema also shows nested `propose` envelopes for related capabilities and jobs-to-be-done. Use the field metadata from `/api/v1/submissions/fields/` to confirm when `add`, `create`, `update`, `remove`, or `propose` operations are accepted. - If search returns zero results for a niche domain, check the taxonomy lists, then propose the missing taxonomy instead of assuming the domain is unsupported. - Use product detail pages for structured links to APIs, MCP servers, SDKs, CLI support, reviews, and pricing offers. - Use the public API when you need machine-readable account and sign-up flows. - Use `/api/v1/users/me/` to inspect the authenticated user profile and `/api/v1/users/me/tokens/` to list or create API tokens. Existing tokens can be retrieved, updated, revoked, or rotated through `/api/v1/users/me/tokens/{token_id}/` and `/api/v1/users/me/tokens/{token_id}/rotate/`. - Use `/api/v1/users/me/bookmarks/` to track which products you are using. `POST` to bookmark a product (with optional `notes`, `following`, and `job_to_be_done_ids`), `PATCH` to update notes, following status, or replace associated jobs-to-be-done, and `DELETE` to remove a bookmark from your list. Set `following` to `true` to follow a product for updates; it defaults to `false`. Users can associate any job-to-be-done with a product, not only those already linked in the catalog. - When you detect stale information, preserve evidence and route corrections through the site rather than silently assuming the listing is current. ## Pagination and reference data - All list endpoints use cursor pagination and return `{ "next": , "previous": , "page_size_default": 20, "page_size_max": 100, "results": [ … ] }`. Follow `next` until it is `null`; do not infer page numbers from cursor values. Lists default to `page_size=20` and accept up to `page_size=100`; the `page_size_default` and `page_size_max` fields echo those limits so you do not have to hardcode them. - Authenticated reads are rate-limited to `120` per minute per token (anonymous reads to `25` per minute per IP). On `429`, honor the `Retry-After` header and back off; do not tight-loop retries. - When you enumerate a large reference vocabulary to resolve values for a submission (for example `/api/v1/catalog/licenses/`, which is hundreds of rows), request `?page_size=100` to minimize round-trips, and cache each list once for the batch rather than re-fetching it per submission. Re-fetching reference data per submission is the most common way a batch populator hits the read rate limit. - You can usually avoid the enumeration entirely: reference and taxonomy `add` and `remove` entries, and scalar foreign keys, accept an object's `slug` directly, not only its UUID. Draft from the slugs you already hold and confirm what each field accepts via `/api/v1/submissions/fields/?app_label=&model=`. ______________________________________________________________________ Content licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).