Summarize API

Edit online

Complete API reference for the AI-Services Summarization API that accepts text or files (.txt / .pdf/ .docx) and returns AI-generated summaries.

Overview

The AI-Services Summarization API provides flexible input options and detailed response metadata including token usage and processing time. It supports both direct text input and file uploads for summarization tasks.

API Endpoints:

  • GET /health — Health check
  • POST /v1/summarize — Summarize text or file
  • POST /v1/summarize/jobs — Create async summarization job
  • GET /v1/summarize/jobs — List all summarization jobs
  • DELETE /v1/summarize/jobs — Bulk delete all jobs
  • GET /v1/summarize/jobs/{job_id} — Get job details
  • DELETE /v1/summarize/jobs/{job_id} — Delete a job
  • GET /v1/summarize/jobs/{job_id}/result — Get summarization result
Note: To access API endpoints:
  • In the Endpoints Catalog UI: Click on Digital Assistant and refer to Integration Endpoints.
  • Using CLI: Run the command to retrieve the API endpoints and base URL.
    ai-services application info <appName> --runtime <podman|openshift>

GET /health

Check service health status.

Tags: health

Success Response (200 OK):

Table 1. Response Fields
Field Type Description
status string Service status (e.g., "ok")

POST /v1/summarize

Summarizes input text or uploaded files and returns an AI-generated summary with metadata and token usage.

Tags: Summarization

Request Parameters:

Table 2. JSON Request Parameters
Parameter Type Required Description
text string Yes Plain text content to summarize
level string No Abstraction level: brief, standard (default), or detailed
length integer No (Legacy) Desired summary length in words
stream boolean No Stream response as it is generated (default: false)
Table 3. Form Data Parameters
Parameter Type Required Description
file file Conditional .txt or .pdf file to summarize
level string No Abstraction level: brief, standard (default), or detailed
length integer No (Legacy) Desired summary length in words
stream boolean No Stream response as it is generated (default: false)

Note: Use either level (recommended) or length (legacy), not both.

Request Example:


curl -X POST /v1/summarize \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Artificial intelligence has made significant progress...",
    "level": "brief"
  }'

Success Response (200 OK):


{
  "data": {
    "original_length": 250,
    "summary": "AI has advanced significantly through deep learning and large language models...",
    "summary_length": 22
  },
  "meta": {
    "input_type": "text",
    "model": "ibm-granite/granite-3.3-8b-instruct",
    "processing_time_ms": 1245
  },
  "usage": {
    "input_tokens": 385,
    "output_tokens": 62,
    "total_tokens": 447
  }
}

Error Codes:

Table 4. Error Responses
HTTP Code Error Code Description
400 INVALID_REQUEST Invalid input or request validation failure
413 CONTEXT_LIMIT_EXCEEDED Input size exceeds allowed limits
415 UNSUPPORTED_MEDIA_TYPE Unsupported file format
429 RATE_LIMIT_EXCEEDED Too many requests sent to the API
500 INTERNAL_SERVER_ERROR Unexpected server error

POST /v1/summarize/jobs

Create an asynchronous summarization job for large files.

Content-Type: multipart/form-data

Table 5. Form Data Parameters
Parameter Type Required Description
file file Yes .txt or .pdf file to summarize
level string No 'brief', 'standard' (default), or 'detailed'
job_name string No Human-readable label for the job

Request Example:


curl -X POST http://10.20.188.184:6000/v1/summarize/jobs \
  -F "file=@document.pdf" \
  -F "job_name=Quarterly Report"

Success Response (202 Accepted):

 {
  "job_id": "c355556c-f945-420a-9142-002bcff8fac8"
}

Error Responses

Table 6. Error Responses
Status Condition Body
400 Bad Request - Invalid input or validation error 
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request validation failed",
    "status": 400
  }
}
415 Bad Request - Invalid input or validation error 
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request validation failed",
    "status": 400
  }
}
422 Validation Error 
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string",
      "input": "string",
      "ctx": {}
    }
  ]
}
500 Internal Server Error - Unexpected error occurred 
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500
  }
}

GET /v1/summarize/jobs

Retrieve all summarization jobs with filtering and pagination.

Tags: jobs

Table 7. Query Parameters
Parameter Type Required Description
latest boolean No Return only the most recent job (default: false)
limit integer No Number of records (1–100, default: 20)
offset integer No Records to skip (default: 0)
status string No 'accepted', 'in_progress', 'completed', 'failed'
Success Response - (200) 
{
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0
  },
  "data": [
    {
      "job_id": "string",
      "job_name": "string",
      "status": "accepted",
      "submitted_at": "string",
      "completed_at": "string",
      "updated_at": "string",
      "document_name": "string",
      "document_word_count": 0,
      "level": "string",
      "job_type": "string",
      "metadata": {
        "total_chunks": 0,
        "completed_chunks": 0,
        "failed_chunks": 0,
        "phase": ""
      },
      "error": "string"
    }
  ]
}

Error Responses

Table 8. Error Responses
Status Condition Body
400 Bad Request - Invalid input or validation error 
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request validation failed",
    "status": 400
  }
}
422 Validation Error 
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string",
      "input": "string",
      "ctx": {}
    }
  ]
}
500 Internal Server Error - Unexpected error occurred 
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500
  }
}

DELETE /v1/summarize/jobs

Delete all jobs and associated data.

Table 9. Query Parameters
Parameter Type Required Description
confirm boolean Yes Must be true to confirm deletion

Success Response (204 No Content)

Error Responses

Table 10. Error Responses
Status Condition Body
400 Bad Request - Invalid input or validation error 
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request validation failed",
    "status": 400
  }
}
409 Active jobs exist -
422 Validation Error 
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string",
      "input": "string",
      "ctx": {}
    }
  ]
}
500 Internal Server Error - Unexpected error occurred 
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500
  }
}

GET /v1/summarize/jobs/{job_id}

Retrieve detailed status and metadata for a job.

Table 11. Path Parameters
Parameter Type Required Description
job_id string Yes Unique job identifier
Request Example: 

          curl -X 'GET' \
  'http://10.20.188.184:6000/v1/summarize/jobs/550e8400-e29b-41d4-a716-446655440000' \
  -H 'accept: application/json'
Success Response (200 OK): 
{
  "job_id": "string",
  "job_name": "string",
  "status": "accepted",
  "submitted_at": "string",
  "completed_at": "string",
  "document": {
    "name": "string",
    "status": "string"
  },
  "error": "string",
  "metadata": {
    "additionalProp1": {}
  }
}

Error Responses

Table 12. Error Responses
Status Condition Body
404 Not Found - Resource does not exist 
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found",
    "status": 404
  }
}
422 Validation Error 
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string",
      "input": "string",
      "ctx": {}
    }
  ]
}
500 Internal Server Error - Unexpected error occurred 
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500
  }
}

DELETE /v1/summarize/jobs/{job_id}

Delete a completed or failed job. Only completed or failed jobs can be deleted. Attempting to delete an active job (accepted or in_progress) returns 409 Conflict.

Success Response (204 No Content)

Error Responses

Table 13. Error Responses
Status Condition Body
404 Not Found - Resource does not exist 
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found",
    "status": 404
  }
}
422 Validation Error 
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string",
      "input": "string",
      "ctx": {}
    }
  ]
}
500 Internal Server Error - Unexpected error occurred 
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500
  }
}

GET /v1/summarize/jobs/{job_id}/result

Retrieve the generated summary for a completed job.

Tags: jobs

Success Response (200 OK):

Table 14. Response Fields
Field Type Description
data.summary string Generated summary
meta.strategy string Summarization strategy (direct or chunked)
usage.total_tokens integer Total tokens used
Request Example: 
curl -X 'GET' \
  'http://10.20.188.184:6000/v1/summarize/jobs/550e8400-e29b-41d4-a716-446655440000/result' \
  -H 'accept: application/json'
Success Response (200 OK): 
{
  "data": {
    "additionalProp1": {}
  },
  "meta": {
    "additionalProp1": {}
  },
  "usage": {
    "additionalProp1": {}
  }
}

Error Responses

Table 15. Error Responses
Status Condition Body
404 Not Found - Resource does not exist 
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found",
    "status": 404
  }
}
422 Validation Error 
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string",
      "input": "string",
      "ctx": {}
    }
  ]
}
500 Internal Server Error - Unexpected error occurred 
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500
  }
}

Best Practices

  1. Input Size: Be mindful of the context window limits. Large files may exceed the maximum token limit and result in a 413 error.
  2. Summary Length: The length parameter is a suggestion and currently experimental. The actual length of output summary cannot be guaranteed to follow this input in all scenarios.
  3. File Formats: Only .txt , .docx and .pdf files are supported. Ensure your files are in one of these formats before uploading.
  4. Error Handling: Always implement proper error handling in your client application to gracefully handle API errors.
  5. Streaming: Use the stream parameter when you need real-time feedback for long-running summarization tasks.
  6. Performance: Monitor the processing_time_ms field in responses to understand API performance and optimize your usage patterns.
  7. Token Usage: Track the usage object in responses to monitor token consumption and optimize costs.