{ "openapi": "3.1.0", "info": { "title": "Blinq Public API", "version": "1.0.0", "description": "The Blinq API provides programmatic access to your contacts and notes. Connect Blinq to your existing tools, keep contact records in sync, and build workflows on note summaries and transcripts.\n\nAPI access requires a [Blinq Pro or Business plan](https://blinq.me/pricing) and a verified email address. Keys are personal and scoped: they never grant access beyond what their owner can already see.\n\n## Access scopes\n\nChoose one or more scopes when creating a key.\n\n| Scope | Grants access to |\n| --- | --- |\n| `blinq:contacts:read` | Your personal contacts. Business owners and admins can list contacts; members can retrieve a visible contact by a known ID. |\n| `blinq:cards:read` | Lightweight card summaries and sharing links in your personal workspace and business workspaces you own or administer. |\n| `blinq:notes:read` | Your own notes and transcripts. |\n| `blinq:identity:read` | Your identity and the workspaces you belong to. |\n\n## Creating and revoking keys\n\n1. In the Blinq web app, open Settings > API keys.\n2. Select **Create new key**, choose a name and the scopes your integration needs, then select **Generate API key**.\n3. Copy the key when it is shown. The secret is displayed only once; store it securely.\n\nTo revoke a key, return to Settings > API keys and select **Revoke**. A revoked key stops authenticating new requests immediately.\n\n## Quick start\n\nSend your key to `https://api.blinq.me` as `Authorization: Bearer `. In the documentation playground, enter only the key, without `Bearer`.\n\nList your notes (requires `blinq:notes:read`):\n\n```bash\ncurl 'https://api.blinq.me/v1/notes?limit=5' \\\n -H 'Authorization: Bearer '\n```\n\nContact routes are scoped to one workspace. `GET /v1/workspaces` (requires `blinq:identity:read`) discovers workspace IDs; listing contacts from a known workspace ID needs only `blinq:contacts:read`:\n\n```bash\ncurl 'https://api.blinq.me/v1/workspaces//contacts?limit=5' \\\n -H 'Authorization: Bearer '\n```\n\n## Errors\n\nAll errors return a JSON body with `status` (the HTTP status code), `error` (the HTTP status name, such as `Bad Request`), `code` (a machine-readable error code), `message` (a human-readable description; wording may change, so branch on `code` instead), and `request_id` (the unique ID of the request, also returned as the `X-Request-Id` header). Validation errors may add a `details` array naming each parameter or body field that failed.\n\nAny route can return `400` when query parameters or the body are invalid (unknown query parameters are rejected), `401` when the API key is missing or invalid, `403` when the key is missing a required scope, its owner lacks permission, or the account plan does not include the operation, and `429` when the rate limit is reached (see Rate limits). Any route can also return `500` when an unexpected error occurs (quote `request_id` when contacting support) and `503` when API key verification or the requested operation is unavailable.\n\nThe responses documented on each route below list only the status codes specific to that operation.\n\n## Rate limits\n\nEach person can make up to **25 requests in any 5-second window**, or **300 requests per minute** at a steady rate. The quota is shared across all of their API keys; creating more keys does not increase it. When the limit is reached, the API returns `429 Too Many Requests` with a `Retry-After` header in seconds. Wait that long before retrying." }, "components": { "securitySchemes": { "API key": { "type": "http", "scheme": "bearer", "description": "Send a Blinq API key as `Authorization: Bearer `; enter only the key in the documentation playground.\n\nCreate and revoke keys in the Blinq web app under Settings > API keys.\n\nThe key needs the scopes required by the operation, and public API access requires a Pro or Business plan." } }, "schemas": {} }, "paths": { "/v1/notes": { "get": { "operationId": "listNotes", "summary": "List notes", "tags": [ "Notes" ], "description": "Returns a paginated list of the authenticated user's note metadata.\n\nNotes are sorted by creation time, newest first, unless `order_by` specifies update time. Ties are broken by note ID, so pages are deterministic.\n\nFor an initial sync, page with `order_by=updated_at` until `has_more` is `false`. For incremental syncs, record a checkpoint before each run, pass it as `updated_at_gte` (inclusive) with a small overlap, upsert by `id`, and advance the checkpoint only after every page succeeds.\n\nDeleted notes are omitted. There is no deletion feed; periodically reconcile a complete list of IDs to detect removals. Timestamp filtering alone does not provide lossless synchronization.\n\nGet an individual note to read its content.\n\nRequires the `blinq:notes:read` scope.", "parameters": [ { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "created_after", "required": false, "description": "Return notes created after this ISO 8601 timestamp with a timezone, such as `2026-10-01T00:00:00Z` (exclusive)." }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "created_before", "required": false, "description": "Return notes created before this ISO 8601 timestamp with a timezone, such as `2026-11-01T00:00:00Z` (exclusive)." }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "updated_at_gte", "required": false, "description": "Return notes last updated at or after this ISO 8601 timestamp with a timezone, such as `2026-10-01T00:00:00Z` (inclusive). Deleted notes are excluded." }, { "schema": { "default": "created_at", "type": "string", "enum": [ "created_at", "updated_at" ] }, "in": "query", "name": "order_by", "required": false, "description": "The timestamp used to sort notes in descending order. Keep this value unchanged between pages." }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "cursor", "required": false, "description": "The `next_cursor` from the previous response. Omit on the first request. Keep filters and `order_by` unchanged between pages." }, { "schema": { "default": 25, "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "The maximum number of notes to return per page." } ], "security": [ { "API key": [] } ], "responses": { "200": { "description": "One page of note metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the note." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The custom title set by the user, otherwise the generated title, or `null` when the note has neither." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the user's device created the note, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the note was last updated, as an ISO 8601 timestamp." }, "deleted_at": { "type": "null", "description": "Always `null`. Deleted notes are not returned." }, "status": { "type": "string", "enum": [ "processing", "ready", "failed", "blocked" ], "description": "The processing state of the note.\n\n`processing`: recording or processing is in progress.\n\n`ready`: no recording or processing is pending. Content may be empty or null.\n\n`failed`: processing failed. Partial content may be available.\n\n`blocked`: processing is blocked by the account plan or usage limits." }, "type": { "anyOf": [ { "type": "string", "enum": [ "voice_note", "phone_call", "text" ] }, { "type": "null" } ], "description": "How the note was captured: a recorded `voice_note`, a recorded `phone_call`, or a typed `text` note. `null` when the type is unavailable." }, "share_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A URL for viewing the note in a browser, or `null` when the note has no share link. Reading a note never creates a share link or changes sharing settings." }, "linked_contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the linked contact." }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The display name of the linked contact, or `null` when none is available." }, "workspace_id": { "type": "string", "description": "The personal workspace ID to pass when getting this contact." } }, "required": [ "id", "full_name", "workspace_id" ], "additionalProperties": false }, "description": "The contacts linked to the note, or an empty array when there are none. Retrieving a linked contact requires `blinq:contacts:read` and contact access." } }, "required": [ "id", "title", "created_at", "updated_at", "deleted_at", "status", "type", "share_url", "linked_contacts" ], "additionalProperties": false, "description": "Note metadata.", "example": { "id": "note-id", "title": "Meeting notes", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "deleted_at": null, "status": "ready", "type": "voice_note", "share_url": "https://note.blinq.me/share-id", "linked_contacts": [ { "id": "contact-id", "full_name": "Jane Doe", "workspace_id": "workspace-id" } ] } }, "description": "Note metadata for this page. Get an individual note to read its content." }, "has_more": { "type": "boolean", "description": "Whether another page of notes is available." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cursor for the next page. When `has_more` is `true`, pass this value as `cursor`. Otherwise, this value is `null`." }, "total_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The total number of notes matching the filters. Returned on the first page; `null` on subsequent pages." } }, "required": [ "notes", "has_more", "next_cursor", "total_count" ], "additionalProperties": false, "description": "One page of note metadata." }, "examples": { "example1": { "value": { "notes": [ { "id": "note-id", "title": "Meeting notes", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "deleted_at": null, "status": "ready", "type": "voice_note", "share_url": "https://note.blinq.me/share-id", "linked_contacts": [ { "id": "contact-id", "full_name": "Jane Doe", "workspace_id": "workspace-id" } ] } ], "has_more": false, "next_cursor": null, "total_count": 1 } }, "example2": { "value": { "notes": [ { "id": "note-id", "title": "Meeting notes", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "deleted_at": null, "status": "ready", "type": "voice_note", "share_url": "https://note.blinq.me/share-id", "linked_contacts": [ { "id": "contact-id", "full_name": "Jane Doe", "workspace_id": "workspace-id" } ] } ], "has_more": true, "next_cursor": "opaque-page-2", "total_count": 3 } }, "example3": { "value": { "notes": [ { "id": "note-id-2", "title": "Meeting notes", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "deleted_at": null, "status": "ready", "type": "voice_note", "share_url": "https://note.blinq.me/share-id", "linked_contacts": [ { "id": "contact-id", "full_name": "Jane Doe", "workspace_id": "workspace-id" } ] } ], "has_more": true, "next_cursor": "opaque-page-3", "total_count": null } }, "example4": { "value": { "notes": [ { "id": "note-id-3", "title": null, "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "deleted_at": null, "status": "ready", "type": "voice_note", "share_url": null, "linked_contacts": [ { "id": "contact-id", "full_name": "Jane Doe", "workspace_id": "workspace-id" } ] } ], "has_more": false, "next_cursor": null, "total_count": null } } } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } } } } }, "/v1/notes/search": { "get": { "operationId": "searchNotes", "summary": "Search notes", "tags": [ "Notes" ], "description": "Searches the authenticated user's indexed note titles and bodies, including recording summaries and saved text, using keyword and semantic matching.\n\nReturns up to `limit` results ordered from most to least relevant. Search does not support pagination. `is_truncated` indicates that additional results were found.\n\nNew or updated notes may be missing until indexing completes. Changing `limit` can change the ranking. Use the list endpoint to retrieve all notes and the get endpoint to read note content.\n\nRequires the `blinq:notes:read` scope.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "example": "launch pricing", "in": "query", "name": "query", "required": true, "description": "Search terms to match against indexed titles and bodies, including recording summaries and saved text." }, { "schema": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 25 }, "in": "query", "name": "limit", "required": false, "description": "The maximum number of search results to return. Search does not support pagination." } ], "security": [ { "API key": [] } ], "responses": { "200": { "description": "Search results ordered by relevance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the note." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The custom title set by the user, otherwise the generated title, or `null` when the note has neither." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the user's device created the note, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the note was last updated, as an ISO 8601 timestamp." }, "deleted_at": { "type": "null", "description": "Always `null`. Deleted notes are not returned." }, "status": { "type": "string", "enum": [ "processing", "ready", "failed", "blocked" ], "description": "The processing state of the note.\n\n`processing`: recording or processing is in progress.\n\n`ready`: no recording or processing is pending. Content may be empty or null.\n\n`failed`: processing failed. Partial content may be available.\n\n`blocked`: processing is blocked by the account plan or usage limits." }, "type": { "anyOf": [ { "type": "string", "enum": [ "voice_note", "phone_call", "text" ] }, { "type": "null" } ], "description": "How the note was captured: a recorded `voice_note`, a recorded `phone_call`, or a typed `text` note. `null` when the type is unavailable." }, "share_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A URL for viewing the note in a browser, or `null` when the note has no share link. Reading a note never creates a share link or changes sharing settings." }, "linked_contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the linked contact." }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The display name of the linked contact, or `null` when none is available." }, "workspace_id": { "type": "string", "description": "The personal workspace ID to pass when getting this contact." } }, "required": [ "id", "full_name", "workspace_id" ], "additionalProperties": false }, "description": "The contacts linked to the note, or an empty array when there are none. Retrieving a linked contact requires `blinq:contacts:read` and contact access." } }, "required": [ "id", "title", "created_at", "updated_at", "deleted_at", "status", "type", "share_url", "linked_contacts" ], "additionalProperties": false, "description": "Note metadata.", "example": { "id": "note-id", "title": "Meeting notes", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "deleted_at": null, "status": "ready", "type": "voice_note", "share_url": "https://note.blinq.me/share-id", "linked_contacts": [ { "id": "contact-id", "full_name": "Jane Doe", "workspace_id": "workspace-id" } ] } }, "description": "Note metadata ordered from most to least relevant. Results may omit notes that have not been indexed." }, "is_truncated": { "type": "boolean", "description": "Whether this search found more results than `limit`. A value of `false` does not guarantee that every note was searched. Use the list endpoint to retrieve all notes." } }, "required": [ "notes", "is_truncated" ], "additionalProperties": false, "description": "Search results ordered by relevance." }, "example": { "notes": [ { "id": "note-id", "title": "Pricing discussion", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "deleted_at": null, "status": "ready", "type": "phone_call", "share_url": null, "linked_contacts": [] } ], "is_truncated": false } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } } } } }, "/v1/notes/query": { "post": { "operationId": "queryNotes", "summary": "Ask a question about notes", "tags": [ "Notes" ], "description": "Generates an answer to a question using the authenticated user's note titles and note bodies (AI summaries for recordings, saved text for typed notes). Transcripts are not used, and each note body is truncated to 8,000 UTF-16 code units.\n\nPass between 1 and 8 of your own `note_ids` to answer from specific notes, or omit the field to let the API select up to 10 of the most relevant notes automatically.\n\nThe answer contains inline markers such as `[1]` or `[1, 2]`: one-based positions in `citations`, where each unique note is numbered in order of first appearance and repeat references reuse the same number.\n\nWhen no accessible notes match, the answer is `No accessible notes were available to answer this question.` If an answer cannot be generated, the request fails with `503` and the message `Blinq could not generate an answer. Try again later.`\n\nRequires the `blinq:notes:read` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "A natural-language question. Answers draw on note titles and note bodies (the AI summary for a recording or the saved text of a typed note), not transcripts. Each note body is truncated to 8,000 UTF-16 code units." }, "note_ids": { "description": "Restricts the answer to between 1 and 8 notes you own. Omit to let the API select up to 10 of the most relevant notes automatically. IDs of inaccessible notes are ignored.", "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example1": { "value": { "query": "What did we decide about the launch?" } }, "example2": { "value": { "query": "What follow-up actions did we agree on?", "note_ids": [ "note-id-1", "note-id-2" ] } } } } } }, "security": [ { "API key": [] } ], "responses": { "200": { "description": "The generated answer and its cited notes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string", "description": "The generated answer. Inline markers such as `[1]` or `[1, 2]` are one-based positions in `citations`. Each unique note is numbered in order of first appearance, and repeat references reuse the same number. When no accessible notes match, the answer is `No accessible notes were available to answer this question.`" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The cited note ID." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The custom title of the cited note, otherwise its generated title, or `null` when it has neither." }, "share_url": { "type": "string", "description": "A URL to view the cited note in a browser. Access follows the existing sharing settings; querying notes does not change them." } }, "required": [ "id", "title", "share_url" ], "additionalProperties": false }, "description": "The unique source notes, in order of first appearance in the answer. Empty when the answer has no citations." } }, "required": [ "answer", "citations" ], "additionalProperties": false, "description": "The generated answer and its cited notes." }, "example": { "answer": "The launch moved to November [1] and the pricing page still needs sign-off [1, 2]. Reply to Dana once legal approves. [2]", "citations": [ { "id": "note-id-1", "title": "Launch planning", "share_url": "https://note.blinq.me/share-id-1" }, { "id": "note-id-2", "title": "Call with Dana", "share_url": "https://note.blinq.me/share-id-2" } ] } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } }, "413": { "description": "Payload too large - The request body exceeds the maximum allowed size", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Payload too large - The request body exceeds the maximum allowed size" }, "example": { "status": 413, "error": "Payload Too Large", "code": "invalid_request", "message": "Request body is too large", "request_id": "req-1" } } } }, "415": { "description": "Unsupported media type - The request body must be `application/json`", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unsupported media type - The request body must be `application/json`" }, "example": { "status": 415, "error": "Unsupported Media Type", "code": "unsupported_media_type", "message": "Unsupported Media Type: text/plain", "request_id": "req-1" } } } } } } }, "/v1/notes/{id}": { "get": { "operationId": "getNote", "summary": "Get note", "tags": [ "Notes" ], "description": "Gets a note owned by the authenticated user, including its content or AI summary when available.\n\nMissing notes and notes owned by another user both return `404`.\n\nRequires the `blinq:notes:read` scope.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true, "description": "The note ID." } ], "security": [ { "API key": [] } ], "responses": { "200": { "description": "The requested note.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the note." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The custom title set by the user, otherwise the generated title, or `null` when the note has neither." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the user's device created the note, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the note was last updated, as an ISO 8601 timestamp." }, "deleted_at": { "type": "null", "description": "Always `null`. Deleted notes are not returned." }, "status": { "type": "string", "enum": [ "processing", "ready", "failed", "blocked" ], "description": "The processing state of the note.\n\n`processing`: recording or processing is in progress.\n\n`ready`: no recording or processing is pending. Content may be empty or null.\n\n`failed`: processing failed. Partial content may be available.\n\n`blocked`: processing is blocked by the account plan or usage limits." }, "type": { "anyOf": [ { "type": "string", "enum": [ "voice_note", "phone_call", "text" ] }, { "type": "null" } ], "description": "How the note was captured: a recorded `voice_note`, a recorded `phone_call`, or a typed `text` note. `null` when the type is unavailable." }, "share_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A URL for viewing the note in a browser, or `null` when the note has no share link. Reading a note never creates a share link or changes sharing settings." }, "linked_contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the linked contact." }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The display name of the linked contact, or `null` when none is available." }, "workspace_id": { "type": "string", "description": "The personal workspace ID to pass when getting this contact." } }, "required": [ "id", "full_name", "workspace_id" ], "additionalProperties": false }, "description": "The contacts linked to the note, or an empty array when there are none. Retrieving a linked contact requires `blinq:contacts:read` and contact access." }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The stored body: an AI summary for a recording or saved text for a text note. `null` means no body is stored; an empty stored body remains `\"\"`. Use `status` to determine processing state." }, "content_format": { "type": "null", "description": "Always `null`: the backend does not record the content format. Treat the stored body as plain text unless your integration explicitly supports its markup." }, "source": { "anyOf": [ { "type": "string", "enum": [ "mobile", "watch", "device" ] }, { "type": "null" } ], "description": "The device type that recorded the note: a `mobile` phone, a `watch`, or the Blinq notetaker `device`. `null` when unknown." } }, "required": [ "id", "title", "created_at", "updated_at", "deleted_at", "status", "type", "share_url", "linked_contacts", "content", "content_format", "source" ], "additionalProperties": false, "description": "The requested note." }, "example": { "id": "note-id", "title": "Meeting notes", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "deleted_at": null, "status": "ready", "type": "voice_note", "share_url": "https://note.blinq.me/share-id", "linked_contacts": [ { "id": "contact-id", "full_name": "Jane Doe", "workspace_id": "workspace-id" } ], "content": "## Next steps\n\n- Share the project proposal.", "content_format": null, "source": "mobile" } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } }, "404": { "description": "Not found - The note does not exist or belongs to another user", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Not found - The note does not exist or belongs to another user" }, "example": { "status": 404, "error": "Not Found", "code": "not_found", "message": "The requested resource was not found.", "request_id": "req-1" } } } } } } }, "/v1/notes/{id}/transcript": { "get": { "operationId": "getNoteTranscript", "summary": "Get note transcript", "tags": [ "Notes" ], "description": "Gets the complete plain-text transcript of a voice note or phone call owned by the authenticated user.\n\nReturns `text: null` when no transcript is stored. An empty stored transcript is returned as `text: \"\"` with `status: \"available\"`. Check `status` and `retry_after` before polling.\n\nTranscripts are returned in full, without pagination.\n\nMissing notes and notes owned by another user both return `404`.\n\nRequires the `blinq:notes:read` scope.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true, "description": "The note ID." } ], "security": [ { "API key": [] } ], "responses": { "200": { "description": "The requested note transcript.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "processing", "recording", "blocked", "failed", "unavailable", "not_applicable" ], "description": "available: text is ready; processing: retry later; recording: capture is ongoing; blocked: action is required in Blinq; failed: processing failed; unavailable: no transcript exists; not_applicable: a typed note." }, "retry_after": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Suggested polling delay in seconds while processing; null for other states." }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The complete plain-text transcript, or `null` when none is stored. An empty stored transcript is returned as `\"\"` with status `available`." } }, "required": [ "status", "retry_after", "text" ], "additionalProperties": false, "description": "The requested note transcript." }, "examples": { "example1": { "value": { "status": "available", "retry_after": null, "text": "Let's send the proposal tomorrow." } }, "example2": { "value": { "status": "available", "retry_after": null, "text": "" } }, "example3": { "value": { "status": "processing", "retry_after": 5, "text": null } }, "example4": { "value": { "status": "not_applicable", "retry_after": null, "text": null } } } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } }, "404": { "description": "Not found - The note does not exist or belongs to another user", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Not found - The note does not exist or belongs to another user" }, "example": { "status": 404, "error": "Not Found", "code": "not_found", "message": "The requested resource was not found.", "request_id": "req-1" } } } } } } }, "/v1/me": { "get": { "operationId": "getMe", "summary": "Get the authenticated user", "tags": [ "Me" ], "description": "Returns the user the supplied API key acts as: their `user_id` and their sign-in `email`, which is `null` when the user has none.\n\nUse it to confirm whose account an integration is accessing before listing workspaces or fetching data. The user is derived from the API key; the endpoint accepts no parameters.\n\nRequires the `blinq:identity:read` scope.", "security": [ { "API key": [] } ], "responses": { "200": { "description": "The authenticated user the API key acts as.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The ID of the user the API key acts as." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The user's sign-in email address, or null when the user has none." } }, "required": [ "user_id", "email" ], "additionalProperties": false, "description": "The authenticated user the API key acts as." }, "example": { "user_id": "user_123", "email": "person@example.com" } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } } } } }, "/v1/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List workspaces", "tags": [ "Workspaces" ], "description": "Returns every workspace the authenticated user belongs to, including member workspaces, in one response without pagination, filters, or a specified order. An empty array means the user belongs to no workspaces.\n\nUse a workspace's `id` to list or retrieve contacts. The `role` is the API key owner's role in that workspace. Membership alone does not grant contact-list access; the contact endpoints enforce their own permissions, and workspace discovery is only needed when the workspace ID is not already known.\n\nRequires the `blinq:identity:read` scope.", "security": [ { "API key": [] } ], "responses": { "200": { "description": "The authenticated user's workspaces.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The workspace ID to use when filtering or retrieving contacts." }, "name": { "type": "string", "description": "The workspace name." }, "type": { "type": "string", "enum": [ "personal", "business" ], "description": "Whether this is a personal workspace (`personal`) or a business workspace (`business`)." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "The API key owner's role in the workspace: `owner`, `admin`, or `member`. Listing business workspace contacts requires `owner` or `admin`; retrieving a visible contact by known ID also allows `member`." } }, "required": [ "id", "name", "type", "role" ], "additionalProperties": false }, "description": "Every workspace the authenticated user belongs to, without pagination and in no specified order. An empty array means the user belongs to none." } }, "required": [ "workspaces" ], "additionalProperties": false, "description": "The authenticated user's workspaces." }, "example": { "workspaces": [ { "id": "workspace-id", "name": "Acme", "type": "business", "role": "admin" } ] } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } } } } }, "/v1/workspaces/{workspace_id}/contacts": { "get": { "operationId": "listContacts", "summary": "List contacts", "tags": [ "Contacts" ], "description": "Returns a paginated list of contact summaries from your personal workspace or a business workspace you own or administer. Business members receive an empty list. The workspace path segment only narrows which accessible contacts are returned; it never grants additional access.\n\nDeleted contacts, hidden contacts, and company-directory entries are excluded.\n\nContacts are sorted by creation time, newest first, with the contact ID as a tie-breaker, so pages are deterministic.\n\nUse a contact's `id` to retrieve its full details from the same workspace.\n\nRequires the `blinq:contacts:read` scope.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "cursor", "required": false, "description": "The `next_cursor` returned by the previous response. Omit for the first page. Keep filters unchanged between pages." }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "search", "required": false, "description": "Filters contacts using a case-insensitive substring match against card names, job titles, company names, and saved text notes." }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "updated_at_gte", "required": false, "description": "Return contact records last updated at or after this ISO 8601 timestamp with a timezone, such as `2026-10-01T00:00:00Z` (inclusive). Deleted contacts are excluded. Changes to linked resources do not necessarily update the contact record." }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "created_at_gte", "required": false, "description": "Include contacts created at or after this ISO 8601 timestamp with a timezone, such as `2026-10-01T00:00:00Z` (inclusive)." }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "created_at_lte", "required": false, "description": "Include contacts created at or before this ISO 8601 timestamp with a timezone, such as `2026-10-31T23:59:59Z` (inclusive)." }, { "schema": { "default": 25, "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "The maximum number of contacts to return per page." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "workspace_id", "required": true, "description": "The workspace ID. Use an `id` returned by the list workspaces endpoint." } ], "security": [ { "API key": [] } ], "responses": { "200": { "description": "One page of contact summaries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The contact ID." }, "type": { "type": "string", "enum": [ "personal", "business" ], "description": "Whether the contact belongs to a personal workspace (`personal`) or a team workspace (`business`)." }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact's full name from the card, or `null` when no name is available." }, "job_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact's job title." }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the contact's company." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the contact record was created, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the contact record was last updated." }, "workspace_id": { "type": "string", "description": "The ID of the workspace containing this contact." } }, "required": [ "id", "type", "full_name", "job_title", "company_name", "created_at", "updated_at", "workspace_id" ], "additionalProperties": false }, "description": "Contact summaries for this page. Empty when no contacts match the request." }, "has_more": { "type": "boolean", "description": "Whether another page of contacts is available." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cursor for the next page. When `has_more` is `true`, pass this value as `cursor`. Otherwise, this value is `null`." }, "total_count": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The total number of contacts matching the filters across all pages. Returned on the first page; `null` on subsequent pages." } }, "required": [ "contacts", "has_more", "next_cursor", "total_count" ], "additionalProperties": false, "description": "One page of contact summaries." }, "examples": { "example1": { "value": { "contacts": [ { "id": "contact-id", "type": "personal", "full_name": "Jane Doe", "job_title": "Designer", "company_name": "Example", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "workspace_id": "workspace-id" } ], "has_more": true, "next_cursor": "cursor-token", "total_count": 42 } }, "example2": { "value": { "contacts": [ { "id": "contact-id-2", "type": "personal", "full_name": "Jane Doe", "job_title": "Designer", "company_name": "Example", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "workspace_id": "workspace-id" } ], "has_more": true, "next_cursor": "opaque-next-page", "total_count": null } }, "example3": { "value": { "contacts": [ { "id": "contact-id-final", "type": "personal", "full_name": null, "job_title": null, "company_name": null, "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "workspace_id": "workspace-id" } ], "has_more": false, "next_cursor": null, "total_count": null } } } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } }, "404": { "description": "Not found - The workspace was not found or access was denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Not found - The workspace was not found or access was denied" }, "example": { "status": 404, "error": "Not Found", "code": "not_found", "message": "The requested resource was not found.", "request_id": "req-1" } } } } } } }, "/v1/workspaces/{workspace_id}/contacts/{contact_id}": { "get": { "operationId": "getContact", "summary": "Get contact", "tags": [ "Contacts" ], "description": "Gets a contact from the specified workspace, including contact details, tags, saved contact notes, linked note metadata, and capture context. Personal contacts must belong to the key owner. Business owners, admins, and members can retrieve a visible business contact when its ID is known; business members cannot discover these IDs through the list endpoint.\n\nMissing contacts and inaccessible workspaces return `404`.\n\nRequires the `blinq:contacts:read` scope.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "workspace_id", "required": true, "description": "The ID of the workspace containing the contact. Use the `workspace_id` returned when listing contacts." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "contact_id", "required": true, "description": "The contact ID." } ], "security": [ { "API key": [] } ], "responses": { "200": { "description": "The requested contact.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The contact ID." }, "workspace_id": { "type": "string", "description": "The ID of the workspace used to retrieve the contact." }, "type": { "type": "string", "enum": [ "personal", "business" ], "description": "Whether the contact belongs to a personal workspace (`personal`) or a team workspace (`business`)." }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact's first name, or `null` when no first name is saved." }, "middle_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact's middle name." }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact's last name, or `null` when no last name is saved." }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact's full name, or `null` when no name is saved." }, "preferred_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name the contact prefers to use." }, "pronouns": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact's pronouns." }, "job_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact's job title." }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the contact's company." }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact's department within their company." }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact's profile headline." }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The URL of the contact's profile image, or `null` when there is none." }, "company_logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The URL of the contact's company logo, or `null` when there is none." }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The saved value of the contact field." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A saved label, such as `Work`, `Home`, or a custom label. `null` when none is saved." } }, "required": [ "value", "label" ], "additionalProperties": false }, "description": "The contact's email addresses and their labels." }, "phone_numbers": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The saved value of the contact field." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A saved label, such as `Work`, `Home`, or a custom label. `null` when none is saved." }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The stored country code. Values can be a region code such as `US` or a calling code such as `+1`." }, "extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The phone number extension." } }, "required": [ "value", "label", "country_code", "extension" ], "additionalProperties": false }, "description": "The contact's phone numbers and their labels, country codes, and extensions." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The saved value of the contact field." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A saved label, such as `Work`, `Home`, or a custom label. `null` when none is saved." } }, "required": [ "value", "label" ], "additionalProperties": false }, "description": "The contact's website and social profile URLs and their labels." }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The saved value of the contact field." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A saved label, such as `Work`, `Home`, or a custom label. `null` when none is saved." } }, "required": [ "value", "label" ], "additionalProperties": false }, "description": "The contact's postal addresses as text values with labels." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The tag text." } }, "required": [ "value" ], "additionalProperties": false }, "description": "Tags assigned to the contact." }, "contact_notes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The contact note ID." }, "text": { "type": "string", "description": "The saved text of the contact note. Empty saved text is preserved." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the contact note was created, as an ISO 8601 timestamp." } }, "required": [ "id", "text", "created_at" ], "additionalProperties": false }, "description": "Text notes saved on the contact." }, "linked_notes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the linked note." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The custom title, otherwise the generated title, or `null` when it has neither." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the user's device created the note, as an ISO 8601 timestamp." }, "type": { "type": "string", "enum": [ "voice_note", "phone_call", "text" ], "description": "How the linked note was captured: a recorded `voice_note`, a recorded `phone_call`, or a typed `text` note." } }, "required": [ "id", "title", "created_at", "type" ], "additionalProperties": false }, "description": "Metadata for notes linked to the contact, including each note's ID, title, creation time, and type." }, "capture_context": { "anyOf": [ { "type": "object", "properties": { "recorded_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "The saved capture timestamp as ISO 8601, or `null` when unavailable. For business contacts, uses the selected recipient capture time, then recipient sharing time, contact sharing time, or contact capture time, in that order." }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The location recorded when the contact was captured." }, "cardholder_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name on the recipient card, or `null` when unavailable. For business contacts, uses the earliest recipient by capture time (sharing time if capture time is absent); legacy recipients missing both times sort first. Falls back to the contact referrer card when no recipient card is recorded. This does not identify a verified meeting participant." } }, "required": [ "recorded_at", "location", "cardholder_name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Saved capture metadata, not evidence of a meeting. For business contacts, location and cardholder refer to the selected earliest recipient. `null` means no capture metadata is available." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When the contact was created, as an ISO 8601 timestamp." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When the contact was last updated, as an ISO 8601 timestamp." } }, "required": [ "id", "workspace_id", "type", "first_name", "middle_name", "last_name", "full_name", "preferred_name", "pronouns", "job_title", "company_name", "department", "headline", "avatar_url", "company_logo_url", "emails", "phone_numbers", "urls", "addresses", "tags", "contact_notes", "linked_notes", "capture_context", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested contact." }, "example": { "id": "contact-id", "workspace_id": "workspace-id", "type": "business", "first_name": "Jane", "middle_name": null, "last_name": "Doe", "full_name": "Jane Doe", "preferred_name": null, "pronouns": null, "job_title": "Designer", "company_name": "Example", "department": null, "headline": null, "avatar_url": "https://example.com/avatar.png", "company_logo_url": null, "emails": [ { "value": "jane@example.com", "label": "Work" } ], "phone_numbers": [ { "value": "5550100", "label": null, "country_code": "+1", "extension": null } ], "urls": [ { "value": "https://example.com", "label": "Website" } ], "addresses": [ { "value": "123 Example St, Melbourne", "label": "Office" } ], "tags": [ { "value": "Customer" } ], "contact_notes": [ { "id": "contact-note-id", "text": "Follow up next week.", "created_at": "2026-10-01T00:00:00.000Z" } ], "linked_notes": [ { "id": "note-id", "title": "Meeting notes", "created_at": "2026-10-01T00:00:00.000Z", "type": "voice_note" } ], "capture_context": { "recorded_at": "2026-10-01T00:00:00.000Z", "location": "Melbourne", "cardholder_name": "Sam Smith" }, "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z" } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } }, "404": { "description": "Not found - The contact was not found or access was denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Not found - The contact was not found or access was denied" }, "example": { "status": 404, "error": "Not Found", "code": "not_found", "message": "The requested resource was not found.", "request_id": "req-1" } } } } } } }, "/v1/workspaces/{workspace_id}/cards": { "get": { "operationId": "listCards", "summary": "List cards", "tags": [ "Cards" ], "description": "Returns a paginated list of lightweight card summaries from your personal workspace or a business workspace you own or administer. Other workspaces, including business workspaces where you are only a member, return `404`.\n\nDeleted cards, drafts, and card templates are excluded. Each summary includes the public sharing URL for the card.\n\nCards are sorted by creation time, newest first, with the card ID as a tie-breaker, so pages are deterministic. Cursors are bound to the requesting key owner and workspace.\n\nRequires the `blinq:cards:read` scope.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "cursor", "required": false, "description": "The `next_cursor` returned by the previous response. Omit for the first page. Keep the workspace unchanged between pages." }, { "schema": { "default": 25, "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "The maximum number of cards to return per page." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "workspace_id", "required": true, "description": "The workspace ID. Use an `id` returned by the list workspaces endpoint." } ], "security": [ { "API key": [] } ], "responses": { "200": { "description": "One page of card summaries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The card ID." }, "workspace_id": { "type": "string", "description": "The ID of the workspace containing the card." }, "url": { "type": "string", "description": "The public sharing URL for the card. Anyone with the link can view the card." }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first name saved on the card, or `null` when none is saved." }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The last name saved on the card, or `null` when none is saved." }, "job_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The job title saved on the card." }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The company name saved on the card." }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The department saved on the card." } }, "required": [ "id", "workspace_id", "url", "first_name", "last_name", "job_title", "company_name", "department" ], "additionalProperties": false, "description": "The requested card summary.", "example": { "id": "card-id", "workspace_id": "workspace-id", "url": "https://blinq.me/card-id", "first_name": "Jane", "last_name": "Doe", "job_title": "Designer", "company_name": "Example", "department": null } }, "description": "Card summaries for this page. Empty when the workspace has no visible cards." }, "has_more": { "type": "boolean", "description": "Whether another page of cards is available." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cursor for the next page. When `has_more` is `true`, pass this value as `cursor`. Otherwise, this value is `null`." }, "total_count": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The total number of visible cards in the workspace. Returned on the first page; `null` on subsequent pages." } }, "required": [ "cards", "has_more", "next_cursor", "total_count" ], "additionalProperties": false, "description": "One page of card summaries." }, "example": { "cards": [ { "id": "card-id", "workspace_id": "workspace-id", "url": "https://blinq.me/card-id", "first_name": "Jane", "last_name": "Doe", "job_title": "Designer", "company_name": "Example", "department": null } ], "has_more": false, "next_cursor": null, "total_count": 1 } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } }, "404": { "description": "Not found - The workspace was not found or access was denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Not found - The workspace was not found or access was denied" }, "example": { "status": 404, "error": "Not Found", "code": "not_found", "message": "The requested resource was not found.", "request_id": "req-1" } } } } } } }, "/v1/workspaces/{workspace_id}/cards/{card_id}": { "get": { "operationId": "getCard", "summary": "Get card", "tags": [ "Cards" ], "description": "Gets a lightweight card summary from the specified workspace, including the public sharing URL for the card. The workspace must be your personal workspace or a business workspace you own or administer.\n\nMissing cards, cards belonging to a different workspace, and inaccessible workspaces return `404`.\n\nRequires the `blinq:cards:read` scope.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "workspace_id", "required": true, "description": "The ID of the workspace containing the card. Use an `id` from list workspaces." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "card_id", "required": true, "description": "The card ID." } ], "security": [ { "API key": [] } ], "responses": { "200": { "description": "The requested card summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The card ID." }, "workspace_id": { "type": "string", "description": "The ID of the workspace containing the card." }, "url": { "type": "string", "description": "The public sharing URL for the card. Anyone with the link can view the card." }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first name saved on the card, or `null` when none is saved." }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The last name saved on the card, or `null` when none is saved." }, "job_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The job title saved on the card." }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The company name saved on the card." }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The department saved on the card." } }, "required": [ "id", "workspace_id", "url", "first_name", "last_name", "job_title", "company_name", "department" ], "additionalProperties": false, "description": "The requested card summary." }, "example": { "id": "card-id", "workspace_id": "workspace-id", "url": "https://blinq.me/card-id", "first_name": "Jane", "last_name": "Doe", "job_title": "Designer", "company_name": "Example", "department": null } } } }, "400": { "description": "Bad request - Invalid query parameters or body. See `details` for each failing field", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Bad request - Invalid query parameters or body. See `details` for each failing field" }, "example": { "status": 400, "error": "Bad Request", "code": "invalid_request", "message": "The request is invalid.", "request_id": "req-1", "details": [ { "path": "limit", "message": "Too big: expected number to be <=50" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Unauthorized - Missing or invalid API key" }, "example": { "status": 401, "error": "Unauthorized", "code": "unauthorized", "message": "Missing or invalid API key.", "request_id": "req-1" } } } }, "403": { "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Forbidden - Missing scope, insufficient permission, or the plan does not include this operation" }, "examples": { "example1": { "value": { "status": 403, "error": "Forbidden", "code": "forbidden", "message": "You do not have access to the requested resource.", "request_id": "req-1" } }, "example2": { "value": { "status": 403, "error": "Forbidden", "code": "plan_required", "message": "The API key owner must have a Blinq Pro or Business plan to use this endpoint.", "request_id": "req-1" } } } } } }, "404": { "description": "Not found - The card was not found or access was denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status code of the response." }, "error": { "type": "string", "description": "The HTTP status name, such as `Bad Request`." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "plan_required", "not_found", "unsupported_media_type", "rate_limited", "internal_error", "upstream_unavailable" ], "description": "A machine-readable code identifying the error. Use this value for programmatic error handling." }, "message": { "type": "string", "description": "A human-readable description. Wording may change; branch on `code` instead." }, "request_id": { "type": "string", "description": "The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support." }, "details": { "description": "Additional validation errors, when available.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request." }, "message": { "type": "string", "description": "A description of the validation error." } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "status", "error", "code", "message", "request_id" ], "additionalProperties": false, "description": "Not found - The card was not found or access was denied" }, "example": { "status": 404, "error": "Not Found", "code": "not_found", "message": "The requested resource was not found.", "request_id": "req-1" } } } } } } } }, "servers": [ { "url": "https://api.blinq.me" } ], "tags": [ { "name": "Contacts", "description": "List contact summaries or get contact details, saved contact notes, and linked note metadata.\n\nContact lists include personal contacts and contacts in business workspaces the authenticated user owns or administers. Business members receive an empty list, but can retrieve a visible business contact by known ID.\n\nRequires the `blinq:contacts:read` scope." }, { "name": "Cards", "description": "List or get lightweight card summaries: the name, title, company, department, and public sharing URL on each card.\n\nCard routes are scoped to one workspace: your personal workspace or a business workspace you own or administer. Business members cannot read team cards.\n\nRequires the `blinq:cards:read` scope." }, { "name": "Notes", "description": "List note metadata, get note content and transcripts, search notes, or generate answers with citations.\n\nOnly notes owned by the authenticated user are accessible.\n\nRequires the `blinq:notes:read` scope." }, { "name": "Workspaces", "description": "List every workspace the authenticated user belongs to, with its type and their role.\n\nUse a known workspace ID directly, or discover it here. Business contact listing requires owner or admin; retrieving a visible contact by known ID also allows members.\n\nRequires the `blinq:identity:read` scope." }, { "name": "Me", "description": "Identify the user the supplied API key acts as, with their ID and sign-in email.\n\nConfirm whose account an integration is accessing before listing workspaces or fetching data.\n\nRequires the `blinq:identity:read` scope." } ] }