# Arc Intelligence API Developer Guide Source: https://dev.arcxp.com/arc-intelligence/developer-docs/arc-intelligence-api-developer-guide/ Developer guide for Arc Intelligence API **API Reference:** [View the complete Arc Intelligence API specification](https://dev.arcxp.com/api/arc-intelligence-api/) ## Introduction The Arc Intelligence API provides AI-powered content tools for Arc XP customers. This guide will help you integrate the API into your applications, regardless of programming language. ### What’s Available - **Prompt Management** \- Store and render reusable prompt templates with variable substitution - **AI Response Generation** \- Generate text responses from language models with streaming or background processing - **Vector Search** \- Find semantically similar stories, images, and videos using natural language queries - TypeScript SDK - ### Base URL Structure The API endpoint follows this pattern: ``` https://api.{your-org-id}.arcpublishing.com/intelligence/api ``` Replace `{your-org-id}` with your organization identifier. Different environments use subdomains: - Production: `https://api.{your-org-id}.arcpublishing.com/intelligence/api` - Sandbox: `https://api.sandbox.{your-org-id}.arcpublishing.com/intelligence/api` ## Getting Started ### Authentication All API requests require authentication using a Bearer token in the `Authorization` header. Terminal window ```bash curl https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/prompts \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` You can obtain API tokens from the Arc Developer Center. Read more about the developer center [here](https://dev.arcxp.com/api/accessing-arcxp-apis/). ### Your First Request Let’s start with a simple API health check by listing prompts: Terminal window ```bash curl https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/prompts \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` **Response:** ```json { "items": [], "next_token": null } ``` If you receive this response, you’re connected and authenticated successfully. ## Prompt Management Prompts are reusable templates with variable placeholders. They use Mustache-style syntax for variables like `{{variable_name}}`. **Note:** The prompt management endpoints are optional convenience features. You can use the AI response generation endpoints directly without storing prompts. ### Creating a Prompt Create a new prompt template: Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/prompts \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt_id": "article-summary", "prompt_text": "Summarize this article in 3 sentences: {{article_text}}", "variables": ["article_text"] }' ``` **Response (201 Created):** ```json { "prompt_id": "article-summary", "prompt_text": "Summarize this article in 3 sentences: {{article_text}}", "variables": ["article_text"], "version": 1, "updated_at": "2024-01-15T10:30:00Z" } ``` The response includes a `version` number that increments with each update. ### Retrieving a Prompt Get an existing prompt by its ID: Terminal window ```bash curl https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/prompts/article-summary \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` **Response:** ```json { "prompt_id": "article-summary", "prompt_text": "Summarize this article in 3 sentences: {{article_text}}", "variables": ["article_text"], "version": 1, "updated_at": "2024-01-15T10:30:00Z" } ``` ### Updating a Prompt Updates require the current `version` number to prevent conflicts. If someone else updated the prompt since you fetched it, you’ll receive a 409 Conflict error. Terminal window ```bash curl -X PUT https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/prompts/article-summary \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt_id": "article-summary", "prompt_text": "Write a 3-sentence summary of this article: {{article_text}}", "variables": ["article_text"], "version": 1 }' ``` **Response (200 OK):** ```json { "prompt_id": "article-summary", "prompt_text": "Write a 3-sentence summary of this article: {{article_text}}", "variables": ["article_text"], "version": 2, "updated_at": "2024-01-15T11:00:00Z" } ``` The `version` incremented from 1 to 2. ### Rendering a Prompt Fill in template variables to get the final text: Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/prompts/render \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt_id": "article-summary", "variables": { "article_text": "Scientists at MIT have developed a new solar panel that is 40% more efficient than current models." } }' ``` **Response:** ```json { "rendered": "Write a 3-sentence summary of this article: Scientists at MIT have developed a new solar panel that is 40% more efficient than current models.", "prompt_id": "article-summary", "version": 2 } ``` ### Listing Prompts Retrieve all prompts with pagination support: Terminal window ```bash curl "https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/prompts?limit=50" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` **Response:** ```json { "items": [ { "prompt_id": "article-summary", "prompt_text": "Write a 3-sentence summary of this article: {{article_text}}", "variables": ["article_text"], "version": 2, "updated_at": "2024-01-15T11:00:00Z" } ], "next_token": null } ``` If `next_token` is present, use it to fetch the next page: Terminal window ```bash curl "https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/prompts?next_token=TOKEN_VALUE" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ### Deleting a Prompt Remove a prompt permanently: Terminal window ```bash curl -X DELETE https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/prompts/article-summary \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` **Response (204 No Content):** No response body is returned for successful deletions. ## AI Response Generation The API can generate text using language models in two modes: background processing with polling, or real-time streaming. ### Background Response with Polling For background processing, create a response and then poll for completion. **Step 1: Create the Response** Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/responses/create-response \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "input": "Explain quantum computing in simple terms", "reasoning_effort": "low" }' ``` **Response:** ```json { "id": "abc123xyz", "status": "queued", "output_text": null } ``` **Step 2: Poll for Completion** Use the `id` from the previous response to check the status: Terminal window ```bash curl https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/responses/retrieve/abc123xyz \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` **Response (while processing):** ```json { "id": "abc123xyz", "status": "in_progress", "output_text": null } ``` **Response (when complete):** ```json { "id": "abc123xyz", "status": "completed", "output_text": "Quantum computing uses quantum mechanics principles to process information. Unlike traditional computers that use bits (0 or 1), quantum computers use quantum bits or qubits that can be both 0 and 1 simultaneously. This allows them to solve certain complex problems much faster than conventional computers." } ``` Keep polling until `status` is either `completed` or `failed`. Wait about 1 second between poll requests. ### Streaming Responses For real-time output, use Server-Sent Events (SSE) by setting the `Accept` header to `text/event-stream`. Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/responses/create-response \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -d '{ "input": "Write a short story about a robot learning to paint" }' ``` **Response (Server-Sent Events):** ``` event: message_start data: {"type": "message_start"} event: output_text.delta data: {"type": "output_text.delta", "delta": "The robot's"} event: output_text.delta data: {"type": "output_text.delta", "delta": " fingers were"} event: output_text.delta data: {"type": "output_text.delta", "delta": " designed for precision"} ... event: message_stop data: {"type": "message_stop"} ``` The stream starts with `message_start`, followed by multiple `output_text.delta` events containing text chunks, and ends with `message_stop`. ### Structured Output with JSON Schema Constrain responses to match a specific JSON structure: > **Note:** When using structured output with a JSON schema, you must explicitly disable unexpected fields. > Set **`"additionalProperties": false`** on the top-level schema object — and any nested objects if needed — to ensure the model only returns the fields defined in your schema. Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/responses/create-response \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "input": "Analyze this article and extract structured metadata: Scientists at MIT have developed a new type of solar panel that is 40% more efficient than current models.", "reasoning_effort": "minimal", "json_schema": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "description": "A catchy headline under 80 characters" }, "summary": { "type": "string", "description": "A 2-3 sentence summary of the main points" }, "tags": { "type": "array", "items": {"type": "string"}, "description": "Relevant topic tags" }, "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"], "description": "Overall sentiment of the content" } }, "required": ["title", "summary", "tags", "sentiment"] } }' ``` Poll for the result as shown in the background response section. The `output_text` will be valid JSON matching your schema: ```json { "id": "xyz789", "status": "completed", "output_text": "{\"title\": \"MIT Scientists Create Solar Panel 40% More Efficient\", \"summary\": \"Researchers at MIT have developed a new solar panel that is 40% more efficient than current models. This breakthrough could significantly reduce renewable energy costs.\", \"tags\": [\"solar power\", \"renewable energy\", \"materials science\"], \"sentiment\": \"positive\"}" } ``` When including a JSON schema, provide clear descriptions for each property so the model understands what you want. ### Reasoning Effort Levels The `reasoning_effort` parameter controls the tradeoff between speed and quality: - `minimal` \- Fastest, good for simple tasks (default) - `low` \- Quick responses for straightforward requests - `medium` \- Balanced speed and quality - `high` \- Slower but more thorough for complex analysis Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/responses/create-response \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "input": "What is 2+2?", "reasoning_effort": "minimal" }' ``` Use `minimal` or `low` for simple queries, and `high` for complex reasoning tasks. ### Multi-Turn Conversations Provide conversation history as an array of messages: Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/responses/create-response \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "input": [ {"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "The capital of France is Paris."}, {"role": "user", "content": "What is its population?"} ], "reasoning_effort": "low" }' ``` The AI maintains context from previous messages and understands that “its” refers to Paris. ## Vector Search Find semantically similar content across your stories, images, and videos using natural language queries. ### Searching Stories Search story content using a semantic query: Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/vector/search/stories \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": "climate change legislation", "limit": 10 }' ``` **Response:** ```json { "results": [ { "id": "story-123", "score": 0.85, "text": "Congress passed landmark climate change legislation today that aims to reduce carbon emissions by 50% over the next decade...", "metadata": { "headline": "Congress Passes Historic Climate Bill", "publish_date": "2024-01-15T09:00:00Z", "websites": [ { "name": "news-site-id", "sections": ["/politics", "/environment"] } ] } } ] } ``` The `score` represents relevance (higher is more relevant). Results are ordered by score in descending order. ### Filtering Stories by Website and Section Narrow down results using metadata filters: Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/vector/search/stories \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": "election coverage", "limit": 5, "metadata_filter": { "websites": { "my-news-site-id": { "sections": ["/politics", "/elections"] }, "my-blog-id": { "sections": ["/opinion/politics"] } }, "publish_date_after": "2024-01-01T00:00:00Z", "publish_date_before": "2024-12-31T23:59:59Z", "excluded_content_ids": ["story-456", "story-789"] } }' ``` Metadata filters include: - `websites` \- Map of website IDs to section filters - `publish_date_after` \- Include stories published on or after this timestamp - `publish_date_before` \- Include stories published on or before this timestamp - `excluded_content_ids` \- Array of content IDs to exclude from results ### Searching Images Search image content with optional metadata filters: Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/vector/search/images \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": "sunset over mountains", "limit": 20, "metadata_filter": { "licensable": true, "sponsored": false, "created_date_after": "2023-01-01T00:00:00Z" } }' ``` **Response:** ```json { "results": [ { "id": "image-123", "score": 0.92, "text": "Vibrant orange and pink sunset over snow-capped mountain peaks", "metadata": { "subtitle": "Sunset view from Rocky Mountain National Park", "licensable": true, "sponsored": false, "published": true, "created_date": "2023-06-15T14:30:00Z" } } ] } ``` Image metadata filters include: - `licensable` \- Filter by whether the image can be licensed - `sponsored` \- Filter by sponsored content status - `published` \- Filter by publication status - `created_date_after` \- Include images created on or after this timestamp - `created_date_before` \- Include images created on or before this timestamp - `excluded_content_ids` \- Array of content IDs to exclude ### Searching Videos Search video content with category and website filters: Terminal window ```bash curl -X POST https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/vector/search/videos \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": "breaking news coverage", "limit": 10, "metadata_filter": { "category": "news", "websites": { "video-site-id": { "sections": ["/news/breaking"] } }, "published_date_after": "2024-01-01T00:00:00Z", "published_date_before": "2024-12-31T23:59:59Z", "last_published_date_after": "2024-06-01T00:00:00Z" } }' ``` **Response:** ```json { "results": [ { "id": "video-123", "score": 0.88, "metadata": { "category": "news", "websites": [ { "name": "video-site-id", "sections": ["/news/breaking"] } ], "last_updated_date": "2024-01-15T08:00:00Z" } } ] } ``` Video metadata filters include: - `category` \- Filter by video category - `websites` \- Map of website IDs to section filters - `published_date_after` \- Include videos published on or after this timestamp - `published_date_before` \- Include videos published on or before this timestamp - `last_published_date_after` \- Include videos last published on or after this timestamp - `last_published_date_before` \- Include videos last published on or before this timestamp ## Usage Statistics Monitor your API usage by retrieving request counts for a specific month. ### Getting Monthly Usage Retrieve usage statistics for a specific month using the `month` query parameter in `YYYY-MM` format: Terminal window ```bash curl "https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/usage/monthly?month=2024-01" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` **Response:** ```json { "month": "2024-01", "totalRequestCount": 920, "days": [ { "date": "2024-01-01", "totalRequestCount": 42 }, { "date": "2024-01-02", "totalRequestCount": 38 }, { "date": "2024-01-03", "totalRequestCount": 55 } ] } ``` The response includes: - `month` \- The requested month in YYYY-MM format - `totalRequestCount` \- Total metered API requests made during the month - `days` \- Array of daily breakdowns, each containing: - `date` \- The specific date in YYYY-MM-DD format - `totalRequestCount` \- Number of metered requests made on that date ## Error Handling The API uses standard HTTP status codes to indicate success or failure. ### Common Status Codes - **200 OK** \- Request succeeded - **201 Created** \- Resource created successfully - **204 No Content** \- Request succeeded with no response body (typically for DELETE) - **400 Bad Request** \- Invalid input (missing required fields, wrong format) - **404 Not Found** \- Resource doesn’t exist - **409 Conflict** \- Version mismatch when updating a prompt - **422 Unprocessable Entity** \- Request body failed validation ### Error Response Structure Error responses follow this structure: ```json { "detail": "Human-readable error message describing what went wrong" } ``` ### Handling Version Conflicts When updating a prompt, if the version has changed since you fetched it, you’ll receive a 409 Conflict: **Request:** Terminal window ```bash curl -X PUT https://api.{your-org-id}.arcpublishing.com/intelligence/api/v1/prompts/article-summary \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt_id": "article-summary", "prompt_text": "Updated text", "variables": ["article_text"], "version": 1 }' ``` **Response (409 Conflict):** ```json { "detail": "Version conflict: expected version 2, got 1. Fetch the latest version and try again." } ``` To resolve this, fetch the latest version first and then retry the update with the current version number. ### Validation Errors When request validation fails, you’ll receive a 422 status with details: **Response (422 Unprocessable Entity):** ```json { "detail": "Validation failed: missing required field 'prompt_text'" } ``` ## API Reference Summary ### Prompt Management Endpoints | Method | Path | Description | | ------ | ------------------------ | -------------------------------- | | POST | /v1/prompts | Create a new prompt | | GET | /v1/prompts | List all prompts with pagination | | GET | /v1/prompts/{prompt\_id} | Get a specific prompt | | PUT | /v1/prompts/{prompt\_id} | Update an existing prompt | | DELETE | /v1/prompts/{prompt\_id} | Delete a prompt | | POST | /v1/prompts/render | Render a prompt with variables | ### Response Generation Endpoints | Method | Path | Description | | ------ | ------------------------------------- | ------------------------------------------------- | | POST | /v1/responses/create-response | Create a model response (background or streaming) | | GET | /v1/responses/retrieve/{response\_id} | Get response status and output | ### Vector Search Endpoints | Method | Path | Description | | ------ | ------------------------- | -------------------- | | POST | /v1/vector/search/stories | Search story content | | POST | /v1/vector/search/images | Search image content | | POST | /v1/vector/search/videos | Search video content | ### Usage Endpoints | Method | Path | Description | | ------ | ------------------------------- | ---------------------------- | | GET | /v1/usage/monthly?month=YYYY-MM | Get monthly usage statistics | ## Additional Resources - **Developer Center**: Read more about the developer center [here](https://dev.arcxp.com/api/accessing-arcxp-apis/) for API token management and additional documentation - **Community Hub**: Join the Arc XP Community at for support and discussions