{ "openapi": "3.1.0", "info": { "title": "FieldRobin Public API", "version": "1.0.0", "description": "Public, unauthenticated content and agent-commerce endpoints for FieldRobin.\n\nAuthenticated application, account, administrative, webhook, and tokenized endpoints are intentionally excluded.", "contact": { "name": "FieldRobin Support", "email": "support@fieldrobin.dev" } }, "servers": [ { "url": "https://fieldrobin.com/api", "description": "FieldRobin public API" } ], "x-service-info": { "categories": [ "field-service", "agent-commerce", "payments" ], "docs": { "homepage": "https://fieldrobin.com/docs", "llms": "https://fieldrobin.com/llms.txt", "apiReference": "https://fieldrobin.com/openapi.json" }, "discovery": { "acp": "https://fieldrobin.com/.well-known/acp.json", "ucp": "https://fieldrobin.com/.well-known/ucp", "a2a": "https://fieldrobin.com/.well-known/agent.json" } }, "tags": [ { "name": "Public", "description": "Public content and service discovery endpoints." }, { "name": "Agent Commerce" } ], "paths": { "/health": { "get": { "tags": [ "Public" ], "summary": "Health check", "description": "Returns API status. No authentication required.", "operationId": "healthCheck", "security": [], "responses": { "200": { "description": "API is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "version": { "type": "string", "example": "v1" } } } } } } } } }, "/v1/blog/posts": { "get": { "tags": [ "Public" ], "summary": "List published blog posts", "operationId": "listPublicBlogPosts", "security": [], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "locale", "in": "query", "schema": { "type": "string", "enum": [ "en-US", "es-US" ], "default": "en-US" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated blog post summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPostPublicListResponse" } } } } } } }, "/v1/blog/posts/categories": { "get": { "tags": [ "Public" ], "summary": "List blog categories with post counts", "operationId": "listPublicBlogCategories", "security": [], "parameters": [ { "name": "locale", "in": "query", "schema": { "type": "string", "enum": [ "en-US", "es-US" ], "default": "en-US" } } ], "responses": { "200": { "description": "Blog categories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPostCategoryListResponse" } } } } } } }, "/v1/blog/sitemap": { "get": { "tags": [ "Public" ], "summary": "Published blog post slugs for sitemap generation", "operationId": "listPublicBlogSitemap", "security": [], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "Blog sitemap rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPostSitemapResponse" } } } } } } }, "/v1/blog/posts/{slug}": { "get": { "tags": [ "Public" ], "summary": "Get a published blog post by slug", "operationId": "showPublicBlogPost", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "query", "schema": { "type": "string", "enum": [ "en-US", "es-US" ], "default": "en-US" } } ], "responses": { "200": { "description": "Blog post detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPostDetailResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/blog/media/{publicId}": { "get": { "tags": [ "Public" ], "summary": "Stream a blog media asset (fallback when no CDN URL)", "operationId": "showPublicBlogMedia", "security": [], "parameters": [ { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Image bytes", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/government-opportunities/public": { "get": { "tags": [ "Public" ], "summary": "List cached active government opportunities (limited fields)", "operationId": "listPublicGovernmentOpportunities", "security": [], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "keyword", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "naics", "in": "query", "schema": { "type": "string" } }, { "name": "psc", "in": "query", "schema": { "type": "string" }, "description": "Product service code (classification code) prefix filter" }, { "name": "set_aside", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated public opportunity summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GovernmentOpportunityPublic" } } } } } } }, "429": { "description": "Too many requests" } } } }, "/v1/government-opportunities/public/filter-options": { "get": { "tags": [ "Public" ], "summary": "List NAICS and PSC filter options from cached active opportunities", "operationId": "listPublicGovernmentOpportunityFilterOptions", "security": [], "responses": { "200": { "description": "Searchable NAICS and PSC code options", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GovernmentOpportunityFilterOptions" } } } } } }, "429": { "description": "Too many requests" } } } }, "/v1/directory/public": { "get": { "tags": [ "Public" ], "summary": "List published directory businesses", "operationId": "listPublicDirectoryListings", "security": [], "parameters": [ { "name": "zip", "in": "query", "schema": { "type": "string" } }, { "name": "postal_code", "in": "query", "schema": { "type": "string" } }, { "name": "industry", "in": "query", "schema": { "type": "string" } }, { "name": "metro", "in": "query", "schema": { "type": "string" } }, { "name": "min_rating", "in": "query", "schema": { "type": "number" } }, { "name": "min_reviews", "in": "query", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "rating_desc", "rating_asc", "reviews_desc", "name_asc" ] } }, { "$ref": "#/components/parameters/PageParam" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Paginated directory listings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryListingPublicListResponse" } } } } } } }, "/v1/directory/public/filter-options": { "get": { "tags": [ "Public" ], "summary": "Directory filter options", "operationId": "listPublicDirectoryFilterOptions", "security": [], "responses": { "200": { "description": "Industries, metros, postal codes", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/directory/public/{slug}": { "get": { "tags": [ "Public" ], "summary": "Directory listing detail", "operationId": "getPublicDirectoryListing", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listing detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryListingPublicResponse" } } } }, "404": { "description": "Not found" } } } }, "/v1/government-opportunities/public/sitemap": { "get": { "tags": [ "Public" ], "summary": "List active government contract slugs for SEO sitemap generation", "operationId": "listPublicGovernmentOpportunitySitemap", "security": [], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } } ], "responses": { "200": { "description": "Paginated slug rows for indexable active opportunities", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GovernmentOpportunitySitemapEntry" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } } } } } } }, "429": { "description": "Too many requests" } } } }, "/v1/government-opportunities/public/{identifier}": { "get": { "tags": [ "Public" ], "summary": "View a government opportunity by SEO slug or legacy notice ID", "operationId": "showPublicGovernmentOpportunity", "security": [], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SEO slug (preferred) or legacy SAM.gov notice_id" } ], "responses": { "200": { "description": "Full public opportunity detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GovernmentOpportunityDetail" } } } } } }, "404": { "description": "Opportunity not found" }, "429": { "description": "Too many requests" } } } }, "/v1/agent": { "get": { "tags": [ "Agent Commerce" ], "summary": "Describe public agent commerce surfaces", "operationId": "getAgentCommerceDiscovery", "security": [], "responses": { "200": { "description": "Agent commerce discovery links and protocol documents", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/agent/paid-reference": { "get": { "tags": [ "Agent Commerce" ], "summary": "Retrieve a paid agent content reference", "description": "Protected with x402. An unpaid request returns HTTP 402 with payment\nrequirements. A successful payment returns the agent resource.\n", "operationId": "getPaidAgentReference", "security": [], "x-payment-info": { "intent": "charge", "method": "tempo", "amount": "1", "currency": "USD", "description": "One paid FieldRobin agent content reference." }, "responses": { "200": { "description": "Paid agent content reference", "content": { "application/json": { "schema": { "type": "object", "required": [ "resource", "content", "protocol" ], "properties": { "resource": { "type": "string" }, "content": { "type": "string" }, "protocol": { "type": "string", "example": "x402" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "503": { "description": "x402 wallet or facilitator configuration is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } } } }, "/v1/agent/a2a": { "get": { "tags": [ "Agent Commerce" ], "summary": "Return the FieldRobin A2A Agent Card", "operationId": "getAgentCommerceCard", "security": [], "responses": { "200": { "description": "A2A Agent Card", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "tags": [ "Agent Commerce" ], "summary": "Handle a minimal A2A message/send request", "operationId": "sendAgentCommerceMessage", "security": [], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "id", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "message/send" ] } } } } } }, "responses": { "200": { "description": "JSON-RPC task response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid Idempotency-Key header or JSON-RPC request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } } } }, "/v1/agent/ucp": { "get": { "tags": [ "Agent Commerce" ], "summary": "Return the UCP REST service entry point", "operationId": "getUcpAgentService", "security": [], "responses": { "200": { "description": "UCP service profile", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/agent/ucp/checkout": { "post": { "tags": [ "Agent Commerce" ], "summary": "Start a UCP content checkout handoff", "description": "Returns a UCP checkout session that hands payment to the protected resource.", "operationId": "createUcpAgentCheckout", "security": [], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "UCP checkout handoff", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid Idempotency-Key header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } } } } }, "components": { "parameters": { "IdempotencyKeyHeader": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional opaque key for safe retries. Reusing the same key with an equivalent request replays the original response and includes `Idempotency-Replayed: true`; using it with a different request returns `409 IDEMPOTENCY_KEY_REUSED`. Maximum 128 visible ASCII characters.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "PageParam": { "name": "page", "in": "query", "required": false, "description": "Page number (default 1, 20 items per page)", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 2 } } }, "responses": { "NotFound": { "description": "Resource not found or does not belong to the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "example": { "message": "No query results for model." } } } }, "PaymentRequired": { "description": "Payment is required before the resource can be returned.", "headers": { "Payment-Required": { "description": "Protocol-specific payment requirements.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "schemas": { "GovernmentOpportunitySitemapEntry": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string" }, "posted_date": { "type": "string", "format": "date-time", "nullable": true }, "last_modified": { "type": "string", "format": "date-time", "nullable": true }, "response_deadline": { "type": "string", "format": "date-time", "nullable": true } } }, "GovernmentOpportunityFilterOption": { "type": "object", "required": [ "code", "label", "count" ], "properties": { "code": { "type": "string" }, "description": { "type": "string", "nullable": true }, "label": { "type": "string" }, "count": { "type": "integer" } } }, "GovernmentOpportunityFilterOptions": { "type": "object", "properties": { "naics": { "type": "array", "items": { "$ref": "#/components/schemas/GovernmentOpportunityFilterOption" } }, "psc": { "type": "array", "items": { "$ref": "#/components/schemas/GovernmentOpportunityFilterOption" } } } }, "GovernmentOpportunityPublic": { "type": "object", "required": [ "id", "title", "status" ], "properties": { "id": { "type": "integer" }, "notice_id": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "title": { "type": "string" }, "organization": { "type": "string", "nullable": true }, "place_city": { "type": "string", "nullable": true }, "place_state": { "type": "string", "nullable": true }, "naics_code": { "type": "string", "nullable": true }, "naics_display": { "type": "string", "nullable": true }, "classification_code": { "type": "string", "nullable": true }, "product_service_code": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "posted_date": { "type": "string", "format": "date-time", "nullable": true }, "response_deadline": { "type": "string", "format": "date-time", "nullable": true }, "set_aside": { "type": "string", "nullable": true }, "status": { "type": "string" }, "is_actionable": { "type": "boolean" } } }, "GovernmentOpportunityDetail": { "allOf": [ { "$ref": "#/components/schemas/GovernmentOpportunityPublic" }, { "type": "object", "properties": { "solicitation_number": { "type": "string", "nullable": true }, "related_notice": { "type": "string", "nullable": true }, "contract_line_item_number": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "base_type": { "type": "string", "nullable": true }, "archive_type": { "type": "string", "nullable": true }, "archive_policy": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "subtier": { "type": "string", "nullable": true }, "office": { "type": "string", "nullable": true }, "organization_type": { "type": "string", "nullable": true }, "organization_name": { "type": "string", "nullable": true }, "full_parent_path_name": { "type": "string", "nullable": true }, "naics_display": { "type": "string", "nullable": true }, "classification_code": { "type": "string", "nullable": true }, "product_service_code": { "type": "string", "nullable": true }, "set_aside": { "type": "string", "nullable": true }, "set_aside_code": { "type": "string", "nullable": true }, "place_of_performance": { "type": "object", "properties": { "street": { "type": "string", "nullable": true }, "street_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "formatted": { "type": "string", "nullable": true } } }, "office_address": { "type": "object", "properties": { "street": { "type": "string", "nullable": true }, "street_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "formatted": { "type": "string", "nullable": true } } }, "award": { "type": "object", "properties": { "amount": { "type": "string", "nullable": true }, "date": { "type": "string", "format": "date-time", "nullable": true }, "awardee_name": { "type": "string", "nullable": true }, "awardee_uei": { "type": "string", "nullable": true } } }, "point_of_contact": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "resource_links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "nullable": true }, "label": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "kind": { "type": "string", "enum": [ "link", "file" ] }, "resource_id": { "type": "string", "nullable": true } } } }, "source_link": { "type": "string", "nullable": true }, "description_cached": { "type": "string", "nullable": true }, "sam_gov_public_url": { "type": "string", "nullable": true }, "additional_info_link": { "type": "string", "nullable": true }, "trade_tags": { "type": "array", "items": { "type": "string" } }, "fit_score": { "type": "number", "nullable": true }, "saved": { "type": "boolean" } } } ] }, "DirectoryListingPhoto": { "type": "object", "required": [ "id", "kind", "public_id", "url", "sort_order" ], "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "photo", "logo" ] }, "public_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "alt_text": { "type": "string", "nullable": true }, "sort_order": { "type": "integer" }, "mime_type": { "type": "string", "nullable": true }, "byte_size": { "type": "integer" }, "original_filename": { "type": "string", "nullable": true } } }, "DirectoryListingPublic": { "type": "object", "required": [ "id", "slug", "name", "industry_key", "industry_label", "metro_key", "review_count", "services", "claim_status", "is_claimed", "logo_url", "photos" ], "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "industry_key": { "type": "string" }, "industry_label": { "type": "string" }, "metro_key": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "website_url": { "type": "string", "format": "uri", "nullable": true }, "address": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true }, "rating": { "type": "number", "nullable": true }, "review_count": { "type": "integer" }, "short_description": { "type": "string", "nullable": true }, "services": { "type": "array", "items": { "type": "string" } }, "claim_status": { "type": "string", "enum": [ "unclaimed", "claim_pending", "claimed" ] }, "is_claimed": { "type": "boolean" }, "google_maps_url": { "type": "string", "format": "uri", "nullable": true }, "logo_url": { "type": "string", "format": "uri", "nullable": true }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryListingPhoto" } } } }, "DirectoryListingPublicResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DirectoryListingPublic" } } }, "DirectoryListingPublicListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryListingPublic" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } } } }, "ErrorMessage": { "type": "object", "required": [ "code", "message", "resolution", "status" ], "properties": { "code": { "type": "string", "example": "RESOURCE_NOT_FOUND" }, "message": { "type": "string", "example": "The given data was invalid." }, "resolution": { "type": "string", "example": "Verify the identifier and try again." }, "status": { "type": "integer", "example": 404 } } }, "BlogPostLocale": { "type": "string", "enum": [ "en-US", "es-US" ] }, "BlogPostPublic": { "type": "object", "properties": { "slug": { "type": "string" }, "locale": { "$ref": "#/components/schemas/BlogPostLocale" }, "title": { "type": "string" }, "excerpt": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "author_name": { "type": "string", "nullable": true }, "cover_image_url": { "type": "string", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "BlogPostDetail": { "allOf": [ { "$ref": "#/components/schemas/BlogPostPublic" }, { "type": "object", "properties": { "body": { "type": "string" }, "meta_description": { "type": "string", "nullable": true } } } ] }, "BlogPostPublicListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPostPublic" } }, "links": { "type": "object" }, "meta": { "type": "object" } } }, "BlogPostDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BlogPostDetail" } } }, "BlogPostCategoryListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "post_count": { "type": "integer" } } } } } }, "BlogPostSitemapResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "locale": { "$ref": "#/components/schemas/BlogPostLocale" }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "last_modified": { "type": "string", "format": "date-time", "nullable": true } } } }, "meta": { "type": "object" } } } } } }